feat: add mawaqit plugin (#53)
* feat: add mawaqit plugin * Address review feedback * Address validator errors
This commit is contained in:
ycf-anon
@@ -0,0 +1,119 @@
|
||||
# Mawaqit
|
||||
|
||||
Prayer times for Noctalia, with a bar widget and panel: live countdown to the next
|
||||
prayer, notifications, optional azan playback, Hijri date, and per-prayer time
|
||||
offsets.
|
||||
|
||||
## Plugin
|
||||
|
||||
| Field | Value |
|
||||
| ------- | ------------------------------------------------------------ |
|
||||
| ID | `ycf/mawaqit` |
|
||||
| Entries | Bar widget: `bar`; panel: `panel`; service: `fetcher` |
|
||||
|
||||
## Requirements
|
||||
|
||||
Install `paplay` (PipeWire/PulseAudio) **or** `pw-cat` on `PATH` — only one is
|
||||
required, used for azan playback. If neither is installed, azan is skipped (a
|
||||
line is logged) and everything else — countdown, panel, notifications — works
|
||||
normally.
|
||||
|
||||
Also requires `pkill` (part of `procps`, present on virtually every distro by
|
||||
default) — used to stop azan playback, since neither player exposes its own
|
||||
stop control.
|
||||
|
||||
Azan audio is **not bundled**. To enable it:
|
||||
|
||||
1. Get your own azan `.mp3` file(s) from wherever you like.
|
||||
2. Copy them into this plugin's `assets/` folder, named exactly `azan1.mp3`,
|
||||
`azan2.mp3`, and/or `azan3.mp3` (only the ones you want to use — you don't
|
||||
need all three).
|
||||
3. In Settings → Plugins → Mawaqit, turn on **Play Azan** and pick which of
|
||||
the three slots to play from **Azan audio**.
|
||||
|
||||
If the selected file isn't present, azan is silently skipped and a line is
|
||||
logged — nothing else is affected.
|
||||
|
||||
## Usage
|
||||
|
||||
- **Left click** the bar widget → open the prayer times panel.
|
||||
- **Right click** the bar widget → cycle its display mode: live countdown →
|
||||
static time → prayer name only.
|
||||
|
||||
Toggle the panel directly:
|
||||
|
||||
```sh
|
||||
noctalia msg panel-toggle ycf/mawaqit:panel
|
||||
```
|
||||
|
||||
The panel shows all five daily prayers plus Sunrise and, during Ramadan, Imsak,
|
||||
with a live countdown banner to whichever is next, the Gregorian and Hijri
|
||||
date, and a refresh button. If azan is playing, a stop button appears next to
|
||||
it.
|
||||
|
||||
## Settings
|
||||
|
||||
Plugin-level (Settings → Plugins → Mawaqit):
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
| -------------------- | -------- | ------- | -------------------------------------------------------------------------- |
|
||||
| `city` | `string` | `London` | Your city name in English. |
|
||||
| `country` | `string` | `UK` | Country name or 2-letter code. |
|
||||
| `method` | `select` | `3` (MWL) | Calculation authority followed in your region. |
|
||||
| `school` | `select` | `0` (Shafi/Maliki/Hanbali) | Asr convention — Hanafi uses a later shadow factor. |
|
||||
| `hijriDayOffset` | `select` | `0` | Shift the displayed Hijri day by −1/0/+1 if it doesn't match local moon sighting. |
|
||||
| `twelveHourFormat` | `bool` | `false` | Show prayer times as 12-hour (e.g. `5:23 AM`) instead of 24-hour. |
|
||||
| `showNotifications` | `bool` | `true` | Show a system notification when each prayer time begins. |
|
||||
| `playAzan` | `bool` | `false` | Play an azan audio file when each prayer time begins. |
|
||||
| `azanFile` | `select` | `azan1.mp3` | Which bundled azan track to play (see Requirements for setup). |
|
||||
| `tune` | `bool` | `false` | Enable the per-prayer minute offsets below. |
|
||||
| `tuneFajr` | `int` | `0` | Fajr offset, in minutes (−60 to 60). |
|
||||
| `tuneDhuhr` | `int` | `0` | Dhuhr offset, in minutes. |
|
||||
| `tuneAsr` | `int` | `0` | Asr offset, in minutes. |
|
||||
| `tuneMaghrib` | `int` | `0` | Maghrib offset, in minutes. |
|
||||
| `tuneIsha` | `int` | `0` | Isha offset, in minutes. |
|
||||
|
||||
Bar widget settings (from the widget's own settings menu):
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
| ------------------- | -------- | ------------------- | ------------------------------------------------------------------ |
|
||||
| `showCountdown` | `bool` | `true` | Show a live countdown to the next prayer instead of the static time. |
|
||||
| `showElapsed` | `bool` | `false` | After a prayer begins, count up (`+`) for up to 1 hour. |
|
||||
| `hidePrayerName` | `bool` | `false` | Show only the time or countdown, without the prayer name. |
|
||||
| `widgetIcon` | `glyph` | `building-mosque` | Bar icon. |
|
||||
| `dynamicIcon` | `bool` | `false` | Show a sun/moon icon matching the current prayer instead of the fixed icon. |
|
||||
| `textColor` | `color` | `on_surface` | Bar text color. |
|
||||
| `iconColor` | `color` | `on_surface` | Bar icon color. |
|
||||
| `activeColor` | `color` | `primary` | Color used when a prayer is happening now or during elapsed mode. |
|
||||
|
||||
## IPC
|
||||
|
||||
Force an immediate refetch (both the service and the bar widget respond):
|
||||
|
||||
```sh
|
||||
noctalia msg plugin ycf/mawaqit:fetcher all refresh
|
||||
```
|
||||
|
||||
Set the bar widget's display mode directly:
|
||||
|
||||
```sh
|
||||
noctalia msg plugin ycf/mawaqit:bar all mode countdown|static|name
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- The background service fetches prayer times once daily from
|
||||
`api.aladhan.com`, sending the configured city/country/method/school as
|
||||
query parameters, plus a second request for the next day's Fajr time (used
|
||||
for the countdown after Isha).
|
||||
- Azan playback runs `paplay` or `pw-cat` against a file **you supply** (see
|
||||
Requirements) — no audio is bundled with this plugin. Playback is stopped
|
||||
by matching the exact file path being played (via `pkill -f`), not a
|
||||
generic pattern — this is the only termination method available since the
|
||||
plugin API doesn't currently expose a PID or stop handle for spawned
|
||||
processes. Stopping happens when the plugin exits or is disabled, or
|
||||
manually from the panel while azan is playing.
|
||||
- The Arabic Hijri date and prayer-time banner are rendered with the bundled
|
||||
Reem Kufi font (`ReemKufi.ttf`), licensed under the SIL Open Font License —
|
||||
see `OFL.txt`.
|
||||
- No compositor-specific behavior — works anywhere Noctalia's bar and panels do.
|
||||
Reference in New Issue
Block a user