Quran Player Daemon: Audio Playback with Desktop Visualization

The Quran Player Daemon is a Python-powered background service built to provide uninterrupted Quranic audio playback while displaying the corresponding verse directly on your desktop using Conky. This elegant combination is ideal for personal devotion, Islamic display panels, or memorization tools. The daemon intelligently manages verse transitions, preserves playback state, and handles Arabic rendering with care.

•Persistent background daemon: enables continuous playback

•Auto verse navigation: seamlessly moves to the next verse

•Custom repeat ranges: for focused memorization or recitation

•Arabic text rendering: with correct shaping and font support

•Cross-platform playback: supports multiple audio engines

•Session persistence: remembers last played verse

•Conky integration: renders verses live on your desktop

Daemon Architecture

At its core, the daemon manages Quranic audio playback and socket communication. Here's how it initializes:

def handle_start(self):
    if not self.verify_audio_config():
        sys.exit(1)

    self.audio_player = AudioPlayer(config, self.log_action)
    with open(config.LOCK_FILE, 'w') as f:
        portalocker.lock(f, portalocker.LOCK_EX)

    with open(config.PID_FILE, "w") as pid_file:
        pid_file.write(str(os.getpid()))

    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    server.bind(config.SOCKET_FILE)
    server.listen(5)
    self.log_action("INFO", "Daemon started. Listening for commands.")

Robust Audio Handling

The audio backend uses pygame's mixer with retry logic:

class AudioPlayer:
    def init_audio(self, max_retries=3):
        for attempt in range(max_retries):
            try:
                pygame.mixer.init(
                    frequency=44100,
                    size=-16,
                    channels=2,
                    buffer=1024
                )
                return True
            except pygame.error:
                time.sleep(1)
        return False

Arabic Text Rendering

Arabic text is shaped and rendered into an image, supporting right-to-left alignment:

def render_arabic_text_to_image(text, output_path, config):
    font = ImageFont.truetype(config['image']['FONT_FILE'], 48)
    image = Image.new("RGBA", (1240, 800), (0, 0, 0, 0))
    draw = ImageDraw.Draw(image)

    # Assume line-by-line rendering has been calculated
    draw.text((image.width - text_width - 20, y), line,
              font=font, fill=color, direction="rtl")
    image.save(output_path, "PNG")

Conky Integration

Verses are displayed using Conky for a minimal, non-intrusive overlay:

conky.config = {
    font = 'Amiri:size=38',
    own_window = true,
    own_window_type = "override",
    own_window_transparent = true,
    alignment = "top_middle",
    gap_x = 25,
    gap_y = 140
}

conky.text = [[
${alignr}${execi 0.5 /path/to/reshape_arabic.sh | head -n 1}
${alignr}${execi 0.5 /path/to/reshape_arabic.sh | sed -n '2p'}
]]

The reshaping script:

#!/bin/bash
# reshape_arabic.sh

arabic_text="$(cat /tmp/quran_verse.txt)"
reshaped_text=$(python reshape_arabic.py "$arabic_text")
echo "$reshaped_text"

Playback and Navigation

Playback auto-advances to the next verse intelligently:

def handle_playback_end(self):
    next_verse = self.get_next_verse()
    if next_verse:
        self.current_verse = next_verse
        self.play_verse(next_verse)

Navigation adapts based on repeat range:

def get_next_verse(self):
    if self.repeat_range:
        start, end = self.repeat_range
        return (surah, (ayah + 1) if ayah < end else start)
    else:
        return (surah, ayah + 1) if ayah < max_ayah else (surah + 1, 0)

Configuration Management

class ConfigManager:
    def __init__(self):
        self.USER_CONFIG_DIR = "~/.config/quran-player"
        self.STATE_FILE = os.path.join(self.USER_CONFIG_DIR, "playback_state.ini")
        self.config = self._load_config()

Installation Guide

The project includes an installer for easy setup:

#!/bin/bash
# install.sh

INSTALL_DIR="$HOME/.quran-player"

copy_application_files() {
    cp daemon.py config_manager.py "$INSTALL_DIR/"
    cp -r audio quran-text "$INSTALL_DIR/"
}

create_cli_wrappers() {
    cat > /usr/local/bin/quran-daemon <<EOF
#!/bin/bash
"$INSTALL_DIR/env/bin/python" "$INSTALL_DIR/daemon.py" "\$@"
EOF
    chmod +x /usr/local/bin/quran-daemon
}

Basic Commands

# Start the daemon
quran-daemon start

# Load specific verse
quran-daemon load 1:1

# Repeat verses 1–7 of Al-Fatiha
quran-daemon repeat 1:1:7

# Show daemon status
quran-daemon status

Performance Highlights

•Thread-based architecture: minimal CPU usage

•Async I/O operations: non-blocking design

•Audio resource optimization: smart reinitialization

•Socket pooling: avoids redundant connections

•Log rotation: keeps disk usage under control

def rotate_log_if_needed(self, logfile):
    max_size = 1_000_000  # 1MB
    if os.path.getsize(logfile) >= max_size:
        os.rename(logfile, f"{logfile}.1")

Real-World Applications

•Islamic Kiosks: Raspberry Pi-powered Quranic display

•Mosques: desktop verse projection during prayer

•Quran Schools: aid in memorization and repetition

•Personal Use: background recitation during work

•Accessibility: support for visually impaired learners

Final Thoughts

The Quran Player Daemon showcases how modern Python tooling can be used to build spiritually meaningful, technically elegant applications. Through Conky and Arabic text processing, it offers a beautiful and non-intrusive way to stay connected with the Quran. Open-source and modular, it's ready for integration with translations, prayer reminders, or mobile extensions.

Resources:

• Project Repo: github.com/neoMOSAID/quran-player

• Conky Docs: conky.sourceforge.net

• Arabic Reshaper: pypi.org/project/arabic-reshaper