Turn your Omarchy machine into an AirPlay speaker. Tap to cast from your phone's AirPlay list, and the audio plays on your speakers or headphones. It's lightning-fast: your phone does the controls, so you don't need a bloated, memory-hungry Linux client. It uses about 50 times less memory than Spotify's desktop app.
It wraps the terminal tool shairport-sync with a GUI: it installs what's
needed, opens only the ports AirPlay uses and only to your local network, puts
the receiver's state in your bar, and shows what's playing in your theme.
| Omarchy | 4.0.3 or newer (plugin API) |
| Audio | PipeWire with pipewire-pulse (the Omarchy default) |
| Discovery | avahi-daemon running (the Omarchy default) |
| Packages | shairport-sync and nqptp — setup installs these |
| Firewall | ufw, if enabled — setup adds the rules |
omarchy plugin add https://github.com/dmatthan/omairplay --enableThen click the new bar icon and choose Run setup.
Setup opens a terminal so you can read every command before approving the password prompt. It:
-
Takes a system snapshot (
omarchy snapshot create), if snapper is configured. -
Installs
shairport-syncandnqptp. -
Enables
nqptpas a system service — it needs privileged ports 319 and 320 for AirPlay 2 clock sync. -
Adds
ufwrules limited to private networks, never to Anywhere, each taggedomairplay:sudo ufw status | grep omairplay -
Writes the receiver's config and a user service under
$HOME.
The plugin itself never needs root while running — only setup, Repair and
removal do, each visibly in a terminal. The receiver is a user service,
omarchy-airplay.service. A machine gets one AirPlay 2 receiver, so if a
packaged shairport-sync unit is enabled, setup names it and says how to
disable it.
Pick your machine from the AirPlay list on your phone, and play:
The bar icon shows the receiver's state: dimmed when off, a cast icon while
playing, the alert colour when it needs repair. Click it for the popup;
right-click turns the receiver on or off. In the popup, j/k or the arrows
move, Enter activates and Esc closes.
The popup shows what's playing and from which device, with the cover art, the sender's volume and a level meter driven by the receiver's real output. Each new track raises a notification. Colours and font follow your Omarchy theme:
Everything else is under Settings in the popup: start at login, speaker name, track notifications, cover art, Repair and Uninstall. Renaming and Repair interrupt playback, so each asks first. The two toggles are also bar settings:
omarchy bar set io.github.dmatthan.omairplay trackNotifications false
omarchy bar set io.github.dmatthan.omairplay showArtwork falseIf the speaker shows up on your phone but won't play, the popup names the reason (a missing firewall rule, a new IPv6 prefix, clock sync down, or no audio arriving) with a Repair button beside it. Repair redoes the setup for the addresses your machine has now: one terminal, one password prompt, the receiver put back as it was. A stalled receiver restarts on its own, up to twice in 15 minutes, before asking.
-
Uninstall in the popup: stops the receiver, disables it at login, deletes its config and cover art, removes the firewall rules it added, and turns
nqptpback off if setup was what enabled it. -
Remove the plugin:
omarchy plugin remove io.github.dmatthan.omairplay
Removing the plugin first is fine — the uninstaller keeps its own copy:
~/.local/state/io.github.dmatthan.omairplay/airplay-remove --systemThe shairport-sync and nqptp packages stay installed.
| Path | What it is |
|---|---|
~/.config/shairport-sync/shairport-sync.conf |
the receiver's config, from your settings |
~/.config/systemd/user/omarchy-airplay.service |
the service that runs the receiver |
~/.cache/shairport-sync/ |
cover art as sent, the rebuilt copies the popup shows, and the receiver's metadata pipe |
~/.local/state/io.github.dmatthan.omairplay/ |
the uninstaller and the helpers the service needs |
ufw rules |
each tagged omairplay, private ranges only — the count depends on which ranges your machine is on |
nqptp.service |
enabled, for AirPlay 2 clock sync |
shairport-sync, nqptp |
packages, from Arch extra |
Only the last three touch anything outside $HOME: no autostart entries, no
PATH changes, no profile edits, no scheduled jobs. Removal reverses all of it.
Omarchy plugins run unsandboxed with your user's permissions, this one included:
- Root is used only by setup, Repair and removal, each run visibly in a terminal.
- Firewall rules cover private ranges only, never Anywhere, and
ufwis never disabled or reset. Every rule is taggedomairplay, and removal finds them by that tag. - Only use the receiver on networks you trust: on public WiFi, someone else might be able to cast to your device. This is a limitation upstream.
- Cover art from the casting device is rebuilt from its image data with all metadata removed, so a malicious image never reaches the shell.
- Track titles, artists, albums and the sending device's name are shown as plain text, length-capped, so markup in them is never interpreted or fetched.
- Commands are called by full path, in an environment the scripts build themselves, so nothing inherited from your session changes what runs.
MIT — see LICENSE.



