Introducing Quran Player: A Cross-Platform Quranic Verse Playback Experience

Version: 1.3.0
License: GPLv3

Overview

In today’s digital age, the Quran deserves a modern, intuitive, and cross‑platform way to be experienced. That’s why we created Quran Player—a powerful application that combines audio playback, synchronized visual display, and beautiful Arabic text rendering. Designed for both casual listeners and scholars alike, Quran Player offers a seamless and engaging experience on Windows, Linux, and more.

What Is Quran Player?

Quran Player is not just an audio player. It is a comprehensive system that:

•Plays Quranic Verses: Enjoy verse‑by‑verse playback with auto‑advance.

•Displays Arabic Text: Experience beautifully rendered Arabic script with proper shaping.

•Offers a Graphical Interface: Control playback easily using our dark‑themed, system‑tray integrated GUI.

•Provides Interactive Search: Quickly find and navigate to any verse using our versatile search tool.

•Renders Images: Generate stunning images of verses with customizable fonts, sizes, colors, and wrapping options.

Every component of the system—from the daemon (quran_player.py) that manages audio playback and state, to the PyQt5‑powered GUI (quran_gui.py), the interactive search tool (quran_search.py), and the image rendering utility (arabic_topng.py)—has been crafted with attention to detail and cross‑platform compatibility.

Key Features

Cross‑Platform Compatibility

•Windows & Linux Support: Separate installation scripts ensure a smooth setup on both Windows and Linux.

•Consistent Experience: Whether you’re on Windows with desktop shortcuts and CLI wrappers, or on Linux with man pages and desktop entries, Quran Player delivers a uniform experience.

Audio Playback & Control

•Verse‑by‑Verse Playback: Listen to recitations that automatically advance, ensuring a natural flow.

•Repeat & Load Functions: Easily repeat a specific range of verses or load any verse using a simple command (e.g., load 2:255).

Beautiful User Interface

•Dark‑Themed Design: Enjoy a modern GUI with a sleek dark palette and intuitive system tray integration.

•Keyboard Shortcuts: Quickly control playback using Space, Left, Right, and Esc keys.

Advanced Search & Image Rendering

•Interactive Search: Utilize the search tool in both command‑line and interactive modes with full right‑to‑left (RTL) support.

•Customizable Image Rendering: Generate images of verses using configurable options such as font, size, colors, and wrapping. Perfect for sharing or offline viewing.

Installation Made Easy

For Windows Users

• Requirements:

•Windows 7 or later

•Python (pre-installed or installed via the setup script)

•Administrator privileges (for some operations)

• Setup Script:

Run the provided Windows setup script (e.g., via python setup.py):

    
python setup.py

This script will:

•Create a virtual environment under %APPDATA%\quran-player

•Copy application files and assets

•Install required dependencies (including pywin32 and winshell)

•Create CLI wrappers in %APPDATA%\quran-player\bin

•Create a desktop shortcut for launching the GUI

• Logs:

Check install.log (generated in the current directory) for details and troubleshooting.

For Linux Users

• Requirements:

•A modern Linux distribution (Ubuntu, Debian, Arch, etc.)

•Bash shell, Python3, and sudo privileges for certain installation steps

• Get the necessary files from github repository

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

• Make Script Executable:

    
chmod +x install.sh

• Run the Installer:

    
./install.sh

The script will:

•Install system dependencies (e.g., python3-venv, feh, pulseaudio-utils)

•Copy application files and assets to ~/.quran-player

•Create a virtual environment and install Python dependencies

•Create CLI wrappers in /usr/local/bin

•Generate a desktop entry in ~/.local/share/applications

•Install the man page for quran-daemon

• Uninstallation:

    
./install.sh --uninstall

Usage

Daemon Commands

The daemon is controlled via CLI commands. Use the generated wrappers:

•Start the Daemon: quran-daemon start

•Stop the Daemon: quran-daemon stop

•Playback Control:

•quran-daemon play – Resume playback

•quran-daemon pause – Pause playback

•quran-daemon toggle – Toggle between play and pause

•quran-daemon next – Advance to the next verse

•quran-daemon prev – Go back to the previous verse

•Load a Specific Verse: quran-daemon load 2:255

•Repeat a Range of Verses: quran-daemon repeat 10:15

•Display Status: quran-daemon status

•Generate Configuration File: quran-daemon config

•Display Detailed Information: quran-daemon info

•Help / About:

•quran-daemon help

•quran-daemon about

GUI Controller

Launch the GUI using the desktop shortcut (Windows) or via the CLI wrapper: quran-gui.

The GUI features:

•Dark theme with a custom Fusion palette

•System tray integration and context menu

•Keyboard shortcuts: Space (play/pause), Left (previous), Right (next), Esc (minimize)

Search Tool

Run the search tool with: quran-search <surah> <start_ayah> [end_ayah]

If no arguments are provided, the tool launches an interactive dialog that will switch the keyboard layout to arabic (for linux users only) and then restore it on exit

Image Rendering

The script arabic_topng.py renders Arabic text to a PNG image with options for wrapping, padding, and color customization. This is used internally by the player for displaying verses.

Configuration

The application is configured via an INI‑style file. By default, the configuration file is located at:

•Linux/macOS: ~/.config/quran-player/config.ini

•Windows: %APPDATA%\quran-player\config.ini

[daemon] Section

•MAX_LOG_SIZE: Maximum log file size (default: 1000000 bytes).

•LOG_LEVEL: Log verbosity. Options: CRITICAL, ERROR, WARNING, INFO, DEBUG, or DISABLED (default: INFO).

•FILES_DIRECTORY: Directory where audio files are stored.

[image] Section

•ENABLE: Enable image display (yes/no). Default: yes on Linux, no on other platforms.

•DEFAULT_RESOLUTION: Image resolution (e.g., 1240x170).

•FONT_FILE: Path to the Arabic font file (default: arabic-font.ttf).

•FONT_SIZE: Font size (default: 48).

•IMAGE_WIDTH: Width of the image in pixels (default: 1240).

•WRAP_WIDTH: Maximum characters per line (default: 170).

•VERTICAL_PADDING: Padding in pixels (default: 20).

•BG_COLOR: Background color (e.g., 0,0,0,0).

•TEXT_COLOR: Text color (e.g., 255,255,255,255).

•HIGHLIGHT_COLOR: Highlight color (e.g., 255,0,0,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.

The Manual

For a complete, detailed description of every command, configuration option, and usage example, refer to the manual below (also available as a man page on Linux and as manual.txt for Windows users):

    
===================================================================
                       Quran Player Daemon Manual
                            Version: v1.3.0
                           Date: Feb 2025
===================================================================

NAME
    quran-daemon - Quran Player Daemon

SYNOPSIS
    quran-daemon [COMMAND] [ARGUMENTS]...

DESCRIPTION
    The Quran Player Daemon is a background service that provides Quranic verse
    playback with synchronized visual display and Arabic text rendering. It supports
    verse-by-verse playback with auto-advance, persistent playback state across
    sessions, repeat functionality, and an optional system tray GUI controller.

COMMANDS
    start
        Start the daemon. This initializes the service, binds the control socket, and
        begins listening for client commands.

    stop
        Stop the daemon. This causes the daemon to shut down gracefully, releasing all
        resources and cleaning up socket and PID files.

    play
        Resume audio playback.

    pause
        Pause the current playback.

    toggle
        Toggle between play and pause.

    next
        Advance to the next verse.

    prev
        Return to the previous verse.

    load
        Load a specific verse. The command expects an argument in the format
        surah:ayah (for example, "2:255").

    repeat
        Repeat a range of verses. Provide the range in the format
        start:end (for example, "10:15"). Note that issuing a play or load command
        cancels repeat mode.

    status
        Display the current playback status, including the surah and ayah numbers and
        playback state.

    config
        Generate the default configuration file in the user configuration directory.

    cleanup
        Remove orphaned runtime files (e.g., stale PID or socket files).

    info
        Display detailed information about daemon status, configuration settings,
        file integrity, and system information.

    help
        Display a help message with a summary of available commands.

    about
        Display program information, including version, project links, and license details.

CONFIGURATION
    The daemon uses an INI-style configuration file. On Linux/macOS, the file is typically
    located at:
        ~/.config/quran-player/config.ini
    On Windows, it is stored in the APPDATA folder.

    The configuration file is divided into two main sections: [daemon] and [image].

    -----------------------------------------------------------------
    [daemon] Section
    -----------------------------------------------------------------
    MAX_LOG_SIZE
        Maximum size (in bytes) of the log file before rotation occurs.
        Default: 1000000.

    LOG_LEVEL
        Log verbosity level. Possible values are:
        CRITICAL, ERROR, WARNING, INFO, DEBUG, or DISABLED.
        Default: INFO.

    FILES_DIRECTORY
        The directory where the audio files are stored. If not specified, a default directory
        (e.g., within the user configuration directory) is used.

    -----------------------------------------------------------------
    [image] Section
    -----------------------------------------------------------------
    ENABLE
        Enable or disable image display. Accepts "yes" or "no". Default is "yes" on Linux
        and "no" on other platforms.

    DEFAULT_RESOLUTION
        Default resolution for the generated image in the format WIDTHxHEIGHT (e.g., "1240x170").

    FONT_FILE
        Path to the Arabic font file used for rendering. By default, the "arabic-font.ttf"
        in the script or user configuration directory is used.

    FONT_SIZE
        Font size for rendering the text. Default: 48.

    IMAGE_WIDTH
        Width of the generated image in pixels. Default: 1240.

    WRAP_WIDTH
        Maximum number of characters per line before wrapping. Default: 170.

    VERTICAL_PADDING
        Vertical padding (in pixels) added to the top and bottom of the image. Default: 20.

    BG_COLOR
        Background color as a comma-separated RGBA string (for example, "0,0,0,0").
        Default: 0,0,0,0.

    TEXT_COLOR
        Text color as a comma-separated RGBA string (for example, "255,255,255,255").
        Default: 255,255,255,255.

    HIGHLIGHT_COLOR
        Highlight color for indicating a specific line, as a comma-separated RGBA string
        (for example, "255,0,0,255").
        Default: 255,0,0,255.

FILES
    quran_player.py
        The main daemon script.
    default_config.ini
        Default configuration file shipped with the daemon.
    config.ini
        User configuration file. Typically located in ~/.config/quran-player/ (Linux/macOS)
        or in the APPDATA folder (Windows).
    daemon.sock or \\.\pipe\quran-daemon (Windows)
        The control socket used for inter-process communication.
    daemon.pid
        File storing the daemon's process ID.
    daemon.log
        Log file for daemon events.

USAGE EXAMPLES
    Start the daemon:
        quran-daemon start

    Stop the daemon:
        quran-daemon stop

    Toggle playback:
        quran-daemon toggle

    Load a specific verse:
        quran-daemon load 2:255

    Repeat a range of verses:
        quran-daemon repeat 10:15

    Display status:
        quran-daemon status

    Generate a new configuration file:
        quran-daemon config

    Display help:
        quran-daemon help

ENVIRONMENT VARIABLES
    The following environment variables can override default configuration values:
    PYTHON_IMAGE_WIDTH
        Overrides the default image width.
    PYTHON_IMAGE_WRAP_WIDTH
        Overrides the default wrap width.
    PYTHON_IMAGE_FONT_SIZE
        Overrides the default font size.
    PYTHON_IMAGE_FONT
        Overrides the default font family.
    PYTHON_IMAGE_BG_COLOR
        Overrides the default background color.
    PYTHON_IMAGE_TEXT_COLOR
        Overrides the default text color.
    PYTHON_IMAGE_HIGHLIGHT_COLOR
        Overrides the default highlight color.
    PYTHON_IMAGE_VERTICAL_PADDING
        Overrides the default vertical padding.

BUGS
    Report bugs and issues via the project's GitHub issue tracker:
        https://github.com/neoMOSAID/quran-player/issues

AUTHOR
    Developed by neoMOSAID.

COPYRIGHT
    This software is released under the GPLv3 License.

===================================================================

Get Involved

Whether you’re a developer or a Quran enthusiast, your feedback and contributions are welcome! Visit our GitHub repository to report issues, submit pull requests, or simply star the project.

Final Thoughts

Quran Player brings together tradition and technology, offering a unique way to interact with the Quran through modern digital means. Explore, enjoy, and help us improve this open‑source project.

Feel free to share this article on social media, include screenshots of the application in action, or embed installation videos to engage with your audience further!