Azizul7m/quran

💻 cross-platform desktop offline Quran reader & player

بسم الله الرحمن الرحيم

Quran Companion

cross-platform desktop Qt-based Quran reader & player

Key Features • Screenshots • Download • Credits • Report Bug • License

Table of Contents

1. About the project
2. Key Features
3. Screenshots
4. Installation
   • Keyboard Shortcuts
5. Compilation
   • Dependencies
   • Build
     • Windows
     • Linux
6. Roadmap
7. Contributing
8. Credits
9. License
10. Contact

About the project ✨

Quran Companion is a cross-platform Quran reader/listener with recitation download capabilities, verse highlighting, resizable quran font, and a variety of tafsir books & translations

Key Features

• Modern UI with dark theme support
• Read the Quran from the mushaf page or read the page verses one-by-one
• Resizable Quran page size
• Quran recitation player
• Option for downloading recitations for a variety of reciters
• Verse highlighting as its read
• A collection of translations & tafsir books for the Quran
• Quran verse search functionality

(back to top)

Screenshots

Arabic UI

(back to top)

Installation ⚙️

Windows

• Online installer can be downloaded from here.

Linux

• Online installer can be downloaded from here.

Keyboard Shortcuts

Key	Description
←	Next page
→	Previous page
Space	start/pause recitation playback
Ctrl + Shift + B	Bookmark current verse
Ctrl + B	Open Bookmarks dialog
Ctrl + F	Open Search dialog
Ctrl + P	Open Preferences dialog
Ctrl + D	Open the download manager
Ctrl + Q	Exit

(back to top)

Compilation 🛠️

To build the application in your system, you'll need to install the dependencies needed for it and package names might be different for each distribution, see Dependencies below for more information. You can also install most of the Qt dependencies via their installer. If you were developing Qt apps before, you probably already have them.

This project uses CMake build system, so you need to install it in order to build the project (on most Linux distributions it is available in the standard repositories as a package called cmake).

Also you can open and build/debug the project in a C++ IDE. For example, in Qt Creator you should be able to simply open CMakeLists.txt via Open File or Project in the menu after installing CMake into your system. More information about CMake projects in Qt Creator.

(back to top)

Dependencies

• GCC
• Qt >= 6.4
  • Qt Tools
  • Qt Multimedia
• CMake >= 3.22

Build

1. Clone the repo, make sure to pass --depth=1 to reduce the download size

  git clone --depth=1 -b main https://github.com/0xzer0x/quran-companion.git

Windows

2. Install Qt using the online installer, make sure to select Qt Multimedia & Qt image formats

3. Add the Qt bin directory to the system PATH variable, usually C:\Qt\6.X.X\mingw_64\bin

4. Build (replace 6.x.x with the Qt version you installed)

  mkdir build
  cd build
  cmake.exe -DCMAKE_PREFIX_PATH="C:\Qt\6.x.x\mingw_64" -DCMAKE_BUILD_TYPE=Release -G "Ninja" ..
  ninja

Linux

2. Install dependencies (through the Qt online installer or using your distro's package manager)

• Ubuntu

sudo apt install build-essential cmake qt6-tools-dev qt6-base-dev qt6-image-formats-plugins qt6-multimedia-dev qt6-l10n-tools qt6-translations-l10n ffmpeg

• Arch linux

sudo pacman -Sy base-devel cmake qt6-base qt6-multimedia qt6-tools qt6-imageformats qt6-translations ffmpeg

3. Build

Note: if you installed Qt through the online installer, you need to pass -DCMAKE_PREFIX_PATH=~/Qt/6.x.x/gcc_64 to CMake in order for the linker to find the Qt libs

  mkdir build
  cd build
  cmake ..
  make

4. If you're using Qt 6.4, you need to set the QT_MEDIA_BACKEND environmental variable to ffmpeg every time you run the executable, you could put the following snippet in a bash file to run the application

export QT_MEDIA_BACKEND=ffmpeg
./quran-companion

(back to top)

Roadmap 🎯

• Add daily verse functionality
• Add bookmarked verses tab
• Enhance search functionality
  • Search in a range of pages only
  • Search in a specific surah only
• Add new tafsir books
  • Aysar Al-Tafasir (al-Jazaeri)
  • al-Tashil li Ulum al-Tanzil (Ibn Juzayy)
  • Adwa' ul-Bayan (al-Shinqiti)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing 💡

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Translation 🌐

To contribute in translating the application, start by:

1. downloading Qt Linguist (either through your package manager or through standalone installers here)

2. fork the repo

3. download the src/translations/qc_template.ts locally

4. open the file in Qt Linguist and choose the langauge to translate to

5. once a sentence is translated, make sure to mark it as finished by clicking the question mark beside it

6. save & exit Qt Linugist

7. rename the file to qc_{lang}.ts where lang is the 2-letter code for the translation language

8. upload the file to your github fork

9. open a pull request (make sure your fork is synced with the main branch)

(back to top)

Credits 📌

The following projects/services were used in development:

• Ayat
• Quran.com API
• Every Ayah recitations
• Mosshaf

(back to top)

License

Distributed under the Waqf General Public License. See license-en.txt for the English version.

(back to top)

Contact

0xzer0x - y.essam2256@nu.edu.eg

Project Link: https://github.com/0xzer0x/quran-companion

(back to top)