How to Install and Use Quran Player on Linux, macOS, and Windows

Exploring the Quran Player: A Comprehensive Guide for Linux Power Users

As a Linux enthusiast, I often seek applications that blend functionality with a seamless user experience. The Quran Player is one such tool that has impressed me. It's a cross-platform Quran playback system that offers synchronized visual displays, making the recitation experience both auditory and visual.

Key Features

•Verse-by-Verse Playback: The application plays each verse individually and automatically advances to the next, ensuring a continuous listening experience.

•Arabic Text Display: It showcases the Arabic script with proper shaping and rendering, enhancing readability.

•Persistent Playback State: Your playback position is saved across sessions, allowing you to resume from where you left off.

•System Tray Controller: A convenient GUI controller resides in the system tray for easy access.

•Cross-Platform Support: Whether you're on Linux, macOS, or Windows, the Quran Player has you covered.

•Customizable Settings: The user-friendly interface lets you tailor configurations to your preferences.

•Multiple Audio File Support: It supports various audio files, accommodating different reciters.

•Interactive Verse Searching: Quickly find specific verses with the built-in search functionality.

Installation Guide

For Linux Users

To get started with the Quran Player on Linux:

    
git clone https://github.com/neoMOSAID/quran-player.git
cd quran-player
./install.sh
    

For Windows and macOS Users

While primarily designed for Linux, the Quran Player can be set up on Windows and macOS, though it's not extensively tested on these platforms. Here's how:

1. Install Python 3.8 or later.
2. Install the required dependencies:

    
pip install -r requirements.txt
    

3. Run the application:

    
python quran_gui.py
    

Using the Quran Player

Daemon Control

The Quran Player operates with a background service (daemon) that manages playback. Here are some essential commands:

    
quran-daemon start        # Start the background service
quran-daemon load 2:255   # Load Al-Baqarah 255
quran-daemon next         # Play the next verse
quran-daemon pause        # Pause playback
    

GUI Control

For those who prefer a graphical interface:

    
quran-gui   # Launch the system tray controller
    

Right-clicking the tray icon provides quick controls, and the application auto-saves your last played position. Display settings are configurable, and multiple reciters are supported.

Configuration

To customize the Quran Player, edit the configuration file located at ~/.config/quran-player/config.ini. Here, you can adjust settings such as audio file locations, text display preferences, font choices, and image rendering options.

For example, to enable image display with specific text settings:

    
[image]
ENABLE = yes
FONT_SIZE = 48
TEXT_COLOR = 255,255,255,255
    

Important Note on Audio Files

For full functionality, the Quran Player requires Quranic audio files named in the specific format XXXYYY.mp3, where XXX is the 3-digit surah number and YYY is the 3-digit ayah number (e.g., 002001.mp3 for Surah 2, Ayah 1). While basic sample files are included, it's recommended to download complete verse-by-verse audio collections from sources like EveryAyah.com. After downloading, place the files in the ~/.config/quran-player/sample/ directory (or your configured FILES_DIRECTORY). Ensure all files follow this naming scheme for seamless playback across all 114 surahs.

Standalone Python Scripts

Beyond its core functionality, the Quran Player includes standalone Python scripts that offer additional features. One notable script is quran_search.py, which provides both command-line and interactive modes to search and display Quranic verses. This tool enhances the user's ability to quickly locate and view specific passages within the Quran.

System Requirements & Dependencies

To ensure the Quran Player functions properly, the following dependencies are required:

Core Dependencies (All Platforms)

•Python 3.8+: The application is built using Python.

•Python Libraries: Install via pip install -r requirements.txt:

•pygame: For audio playback.

•pystray: For the system tray GUI.

•pillow: For image rendering.

•arabic-reshaper and python-bidi: For Arabic text shaping and rendering.

Platform-Specific Requirements

Linux/macOS:

•feh: An image viewer for displaying Arabic text.

•PulseAudio: Serves as the audio backend.

•Arabic font support: Ensure system fonts are installed.

Windows:

•Manual font installation: Copy arabic-font.ttf to C:\Windows\Fonts.

Contributing

We welcome contributions! Please refer my github repository