Athan Pi

Prayer time scheduler for Raspberry Pi that automatically plays the call to prayer (Athan) at correct times with web-based configuration.

Features

• Automatic Scheduling - Fetches prayer times from my-masjid.com API
• Per-Prayer Customization - Individual audio file, volume (0-200%), and speed (0.5x-2.0x) control
• Custom Fajr Time - Override Fajr time with custom HH:MM setting
• Modern Web UI - Responsive interface with light/dark mode
• Audio Processing - Speed adjustments cached, volume applied in real-time
• Reliable Operation - Automatic retry on failure, daily midnight refresh

Quick Start

Development

./run.sh

Access UI at http://localhost:8000

Testing

./run_test.sh  # Uses FakeSource for rapid testing

Audio Files

Place audio files in audio/ directory (mp3):

• fajr.mp3, dhuhr.mp3, asr.mp3, maghrib.mp3, isha.mp3
• Falls back to default.mp3 if specific file is missing
• Speed-adjusted files cached in audio/.processed/ (auto-created)

Configuration

Set in run.sh or as environment variables:

• MY_MASJID_GUID - Your masjid ID from my-masjid.com
• ATHAN_TIMEZONE - IANA timezone (default: Europe/Stockholm)
• ATHAN_DATA_DIR - Data directory (default: /app/data)
• ATHAN_AUDIO_DIR - Audio directory (default: /app/audio)
• ATHAN_SOURCE - Timing source: "my_masjid" or "fake" (default: my_masjid)

Raspberry Pi Deployment

1. Install audio player:

sudo apt install mpg123 ffmpeg

2. Deploy files:

./deploy.sh pi@raspberrypi.local

3. On the Pi, install and start:

cd ~/athan
./ctl.sh install
./ctl.sh start

Service Control

./ctl.sh start   # Start service
./ctl.sh stop    # Stop service
./ctl.sh status  # Check status
./ctl.sh logs    # View logs

API

• GET / - Web UI
• GET /api/timings - Prayer times
• GET /api/settings - Get settings
• POST /api/settings - Update settings
• GET /api/audios - List audio files
• POST /api/test-audio - Test playback
• POST /api/silent - Stop audio
• GET /api/health - Health check

Documentation

• AGENTS.md - Comprehensive guide for AI assistants and developers
• .agents/summary/ - Detailed documentation (architecture, components, workflows, APIs)

Technology Stack

• Backend: Python 3.12, FastAPI, APScheduler
• Frontend: Vanilla JavaScript, Tailwind CSS
• Audio: ffmpeg for speed processing, mpg123 for playback with native volume
• Deployment: systemd service on Raspberry Pi

Development

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run development server
./run.sh

License

Personal project for prayer time automation.