Linux Prayer Indicator

A tiny GNOME / Ubuntu system tray indicator that shows a countdown to the next Islamic prayer (namaz vakti). Prayer times are computed locally with the PrayTimes.org algorithm — no network, no API, no telemetry.

The label updates every 20 seconds and changes color as the next prayer approaches:

Remaining time	Glyph	Meaning
First half of the interval between two prayers	🟢	Plenty of time
Second half of the interval (still ≥ 1 hour)	🟡	Getting closer
Less than 1 hour	🔴	Final warning

Clicking the indicator opens a menu with all of today's prayer times. Desktop notifications fire 1 hour before each prayer and again when the prayer time begins.

---

Türkçe

GNOME/Ubuntu sistem tepsisinde (sağ üst) bir sonraki namaz vaktine kalan süreyi HH:MM formatında gösteren küçük bir uygulama. Vakitler yerel astronomik hesapla (PrayTimes.org) bulunur — internet/API kullanılmaz, veri toplamaz.

Etiket her 20 saniyede bir güncellenir ve yaklaşmaya göre renk değiştirir:

Kalan süre	Sembol	Anlamı
İki vakit arasındaki aralığın ilk yarısı	🟢	Yeterince zaman var
Aralığın ikinci yarısı (≥ 1 saat)	🟡	Yaklaşıyor
1 saatten az	🔴	Son uyarı

Tıkladığında günün tüm vakitlerini gösteren menü açılır. Vakit girdiğinde ve 1 saat kala masaüstü bildirimi düşer.

---

Screenshot

The clock icon, the colored status dot and the HH:MM countdown live next to the system status menu in the GNOME top bar.

Requirements

• Ubuntu 22.04 / 24.04 (or any GNOME desktop with the AppIndicator extension)
• Python ≥ 3.10

System packages (GObject Introspection bindings cannot be installed from PyPI):

sudo apt install \
    python3-gi \
    gir1.2-ayatanaappindicator3-0.1 \
    gir1.2-notify-0.7 \
    libnotify-bin

These are already part of a default Ubuntu Desktop install.

Install

git clone https://github.com/podeveloper/linux-prayer-indicator.git
cd linux-prayer-indicator
./install.sh

install.sh will

1. verify that the system packages above are present,
2. install the Python package into your user environment (using pipx with --system-site-packages if available, otherwise pip install --user),
3. drop a default config.toml at ~/.config/prayer-indicator/config.toml,
4. register an XDG autostart entry and a systemd --user unit.

To start right away without rebooting:

systemctl --user start prayer-indicator
# or:
prayer-indicator

Configuration

Edit ~/.config/prayer-indicator/config.toml. Defaults are tuned for İstanbul and approximate Diyanet times to within a few minutes:

[location]
name      = "İstanbul"
latitude  = 41.0082
longitude = 28.9784
timezone  = 3.0

[method]
fajr_angle    = 18.0
isha_angle    = 17.0
asr_factor    = 1            # 1 = Shafi, 2 = Hanafi
horizon_angle = 0.833

[temkin]                     # per-prayer minute offsets
fajr    = -2
sunrise = -7
dhuhr   = 5
asr     = 4
maghrib = 7
isha    = 1

[display]
language              = "tr" # "tr" or "en"
notify_before_minutes = 60   # 0 = disable
tick_seconds          = 20

For other cities just change latitude, longitude and timezone. Hanafi madhhab users should set asr_factor = 2.

Calibrating temkin against an official calendar

To match a specific local calendar perfectly, run the calibrator against a CSV exported from your authority's monthly table:

python tools/calibrate_temkin.py path/to/diyanet.csv          # preview only
python tools/calibrate_temkin.py path/to/diyanet.csv --write  # update config.toml

The script reads a CSV with the header date,fajr,sunrise,dhuhr,asr,maghrib,isha, recomputes the times for each date with the current [location] and [method] settings, and prints the median deviation per prayer in minutes. Those medians are the temkin offsets that minimize the residual error. A sample is provided at examples/diyanet_sample.csv.

The calibrator is offline; you supply the reference data yourself (copy/paste from the Diyanet site into a spreadsheet, export as CSV).

Run / stop / uninstall

systemctl --user start prayer-indicator       # start
systemctl --user stop  prayer-indicator       # stop
systemctl --user enable prayer-indicator      # auto-start on login (also done via .desktop)

# Quick manual run
prayer-indicator

# Remove autostart
rm ~/.config/autostart/prayer-indicator.desktop
rm ~/.config/systemd/user/prayer-indicator.service

# Uninstall
pipx uninstall linux-prayer-indicator

Accuracy

Times are derived from astronomical formulas. With the default [temkin] adjustments, computed times typically agree with the Diyanet calendar to within 1–3 minutes for İstanbul. They are deterministic and identical year after year, so the indicator keeps working even if you stay offline.

How it works

1. Every 20 seconds the app computes prayer times for yesterday, today and tomorrow with the parameters in config.toml.
2. It builds a chronological list, finds the closest future prayer and the most recent past one.
3. The remaining minutes are rendered as HH:MM and prefixed with a colored circle based on how far we are inside the current inter-prayer interval.
4. libnotify sends a desktop notification 1 hour before each prayer and again when it begins.

The astronomical calculation is a compact port of the public-domain PrayTimes.org algorithm. Pure standard library, ~150 lines, no dependencies beyond the system GTK bindings.

License

MIT — see LICENSE.