homebridge-adhanpod

A Homebridge plugin that plays the adhan on one or more HomePods at prayer time via AirPlay.

• Calculates prayer times from your coordinates using any of the seven major methods
• Automatically plays adhan at each prayer time — no cron, no Pi, no relay
• Choose exactly which of the five daily prayers should be announced
• Play on multiple HomePods at once, in sync
• HomeKit switches (one per enabled prayer) appear in the Home app for manual on-demand triggering
• Randomly rotates between multiple adhan recordings for variety
• Optionally plays the after-adhan dua after each adhan
• Bring your own MP3s — point mediaPath at a folder of your own recordings

Requirements: pyatv must be installed on the Homebridge host.

Installation

1. Install pyatv on the Homebridge host

pip3 install pyatv

Verify:

atvremote --version

If atvremote is not found after installing, note its full path — you'll need it in the config:

which atvremote          # e.g. /home/user/.local/bin/atvremote

2. Find your HomePod(s) Device ID

atvremote scan

Look for each HomePod you want to use in the output and copy its Device ID (format: AA:BB:CC:DD:EE:FF) and IP address. Repeat this for every HomePod you plan to add — the plugin can play on as many as you like, simultaneously.

3. Pair with each HomePod (one-time)

Run this as the same user that Homebridge runs as — credentials are stored per-user. Repeat for every HomePod:

atvremote --id AA:BB:CC:DD:EE:FF --protocol airplay pair

A PIN will appear on the HomePod. Enter it when prompted. You should only need to do this once per device.

Proxmox / LXC users: Check which user Homebridge runs as (ps aux | grep homebridge), then su to that user before running the pair command.

4. Install the plugin

Via the Homebridge UI: Plugins → search "adhanpod" → Install

Or via CLI:

npm install -g homebridge-adhanpod

5. Configure

Add the platform to your Homebridge config.json, or use the Homebridge UI config editor:

{
  "platforms": [
    {
      "platform": "AdhanHomePod",
      "name": "Adhan HomePod",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "method": "ISNA",
      "homepods": [
        { "name": "Kitchen HomePod", "id": "AA:BB:CC:DD:EE:FF", "ip": "192.168.1.42" },
        { "name": "Living Room HomePod", "id": "11:22:33:44:55:66", "ip": "192.168.1.43" }
      ],
      "enabledPrayers": ["fajr", "dhuhr", "asr", "maghrib", "isha"],
      "playDua": true,
      "volume": 50
    }
  ]
}

Restart Homebridge. A switch for each enabled prayer (e.g. Fajr Adhan, Dhuhr Adhan, Asr Adhan, Maghrib Adhan, Isha Adhan) will appear in the Home app.

Configuration Reference

| Field | Required | Description | |---|---|---| | latitude | ✅ | Your latitude (e.g. 40.7128) | | longitude | ✅ | Your longitude (e.g. -74.0060) | | method | ✅ | Calculation method (see below) | | homepods | ✅ | Array of { name?, id, ip? } — one entry per HomePod. All entries play simultaneously. | | enabledPrayers | — | Array of prayers to announce/schedule, from fajr, dhuhr, asr, maghrib, isha. Defaults to all five. | | playDua | — | false to skip the after-adhan dua. Defaults to true. | | volume | — | HomePod playback volume, 0–100. Defaults to 50. | | atvremotePath | — | Full path to atvremote binary if not in Homebridge's $PATH | | mediaPath | — | Path to a folder with your own MP3 files (defaults to bundled files) | | disableAutoPlay | — | true to suppress automatic scheduling (manual switches only) |

Upgrading from 1.0.0? The old single homepodId/homepodIp fields still work as a fallback if homepods is empty, but the config UI now writes to homepods — re-save your config once to migrate.

Calculation Methods

| Value | Description | |---|---| | ISNA | Islamic Society of North America (default) | | MWL | Muslim World League | | Egypt | Egyptian General Authority of Survey | | Makkah | Umm al-Qura University | | Karachi | University of Islamic Sciences, Karachi | | Tehran | Institute of Geophysics, University of Tehran | | Jafari | Shia Ithna Ashari |

Custom Audio Files

By default the plugin uses the bundled recordings in media/:

| File | Used for | |---|---| | Adhan-fajr.mp3 | Fajr (preferred) | | Adhan-Makkah1.mp3 | Regular prayers | | Adhan-Madinah.mp3 | Regular prayers (rotated randomly) | | Adhan-MarwanAlQasas.mp3 | Regular prayers (rotated randomly) | | Adhan-OmarHishamAlArabi.mp3 | Regular prayers (rotated randomly) | | after-adhan-dua.mp3 | Played after every adhan |

To use your own files, set mediaPath to a folder containing any combination of:

• Adhan*.mp3 — any file starting with Adhan is eligible for random selection
• Files with fajr in the name are preferred for Fajr prayer
• after-adhan-dua.mp3 — dua played after each adhan (set playDua: false to disable it entirely)

Troubleshooting

Switches appear but nothing plays

• Check the Homebridge log for [HomePod:<name>] and [atvremote:<name>] lines
• Run the atvremote command manually from the terminal to confirm it works:

  atvremote --id AA:BB:CC:DD:EE:FF --protocol airplay stream_file /path/to/Adhan-Makkah1.mp3

Only some HomePods play

• Each device needs its own one-time pairing (step 3) — an unpaired device will log an error but won't block the others
• Double-check each entry's id in the homepods array against atvremote scan output

atvremote: command not found in Homebridge log

• Set atvremotePath in config to the full path returned by which atvremote

Auth/credentials error

• Re-run the pair command as the user Homebridge runs as (see installation step 3)

Wrong prayer times

• Double-check latitude, longitude, and method in config
• Make sure the system timezone on the Homebridge host is set correctly:

  timedatectl          # Linux

Architecture

Homebridge (your LXC / host)
  ├── adhanScheduler.ts  — calculates times, fires setTimeout for each prayer
  ├── prayerAccessory.ts — one HomeKit Switch per prayer
  ├── homepodPlayer.ts   — spawns atvremote to stream MP3 via AirPlay
  └── media/             — bundled MP3 files
         ↓
      atvremote  →  HomePod (AirPlay)

Prayer times are recalculated daily at 00:01. The scheduler only needs Homebridge to be running — no cron jobs, no Raspberry Pi.