Skip to content
ssandysPublic

About

Omarchy shell bar widget for Roon: now-playing, transport, library search, zone switching and transfer. Backed by a Python daemon that speaks Roon's MOO protocol and publishes MPRIS.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

tonearm

Roon now-playing and transport, in the Omarchy shell bar.

Tonearm shows what's playing on your Roon system — album art, artist, and album — with play/pause, previous/next, seek, and volume, plus the ability to switch which Roon zone the widget follows. It also publishes an MPRIS player on the session bus, so your keyboard's media keys (play/pause, next, previous) control Roon like they would any other player, with no Hyprland configuration required.

Install

  1. Add the plugin and put it in the bar:

    omarchy plugin add https://github.com/ssandys/tonearm.git --enable

    This clones tonearm into ~/.config/omarchy/plugins/ssandys.tonearm/ and enables the bar widget. It appears on the right of the bar straight away, showing an error glyph — there's no daemon behind it yet, which the next two steps fix. Open the popup at any point and its header tells you what it's currently waiting on.

    (omarchy plugin install is an alias for the same thing. To place it somewhere other than the default: omarchy plugin enable ssandys.tonearm --section left.)

  2. Install the one runtime dependency Omarchy doesn't already ship:

    omarchy pkg add python-dbus-next

    (The other Python dependency, websocket-client, is already present on a stock Omarchy install.)

  3. Run setup:

    ~/.config/omarchy/plugins/ssandys.tonearm/setup.sh

    This installs and starts tonearmd, the background daemon that talks to your Roon Core, as a systemd user service (tonearmd.service), plus the small bus proxy it publishes media keys through (tonearmd-bus.service). It starts automatically on every login from then on.

    If automatic discovery cannot see a Core that you know is reachable, supply it explicitly on the first setup:

    ~/.config/omarchy/plugins/ssandys.tonearm/setup.sh --core 192.168.50.44

    Tonearm uses Roon's advertised HTTP/MOO port 9330 and TCP port 9150 by default. HOST can be an IPv4 address or DNS hostname. A Core advertising different ports can be bootstrapped with --http-port PORT and --tcp-port PORT. Re-running this for the same Core is safe and preserves pairing and the pinned zone. It deliberately refuses to replace a different configured Core; switching Cores also has pairing implications and is not part of first-run bootstrap. This also means --core is not a recovery path for a Core that moved to a new address: it refuses the replacement host and preserves any stored Core identity. Use the re-pair/reset path for a moved Core or incorrect identity rather than editing Tonearm's private config.

  4. Open Roon Remote → Settings → Extensions and enable tonearm. tonearmd registers itself with your Roon Core as soon as it starts, but Roon will not talk to it until you approve it here — this is a one-time pairing step per Roon Core. Until you do, the popup header reads Enable tonearm in Roon → Settings → Extensions.

  5. Check that everything came up correctly:

    ~/.config/omarchy/plugins/ssandys.tonearm/setup.sh --check

    This confirms the service is running, the daemon is answering on its socket, and — until you complete step 4 — will tell you it's running but not yet paired. It also reports whether media keys are working (see Media keys).

To update later: omarchy plugin update ssandys.tonearm, then re-run setup.sh. It reinstalls both units and restarts the daemon, so changes take effect immediately; re-running it when nothing changed is harmless.

Once paired, the bar widget starts showing whatever is playing on your followed Roon zone.

The popup's header names the Roon Core you're attached to. If something is wrong — the daemon isn't running, the extension isn't enabled yet, the Core is unreachable — the header says so in place of the Core's name, so you never have to guess why nothing is playing.

What it does on your network

Worth knowing before you install something that runs unsandboxed in your shell.

Finding your Core, once. Roon Cores announce themselves over SOOD, but the standard multicast query draws no reply on many networks (an access point filtering multicast is enough). So on first run only, if no Core is already configured, tonearm scans your local subnet: it opens a TCP connection to one port — 9330, Roon's HTTP/MOO port — on each address in the /24, and sends a SOOD query to whatever answers.

Supplying setup.sh --core HOST writes that explicit address through the same private config path and skips this initial discovery. It does not change later connection or relocation behavior.

Constraints on that scan:

  • First run only. The Core's address is written to ~/.config/tonearm/config.json and reused from then on. Delete that file and it scans again; otherwise it never repeats.
  • Private address space only. Each interface's own IPv4 address is checked with ipaddress.is_private before its /24 is scanned, so a machine with a public address on an interface does not get its neighbours probed.
  • The subnet comes from the interfaces themselves (SIOCGIFADDR), not from a routing lookup — on a host running a VPN, the usual "UDP-connect to a scratch address" trick returns the tunnel's address and would point the scan at an unrelated subnet.
  • At most 512 addresses, total. That is a ceiling on the whole run, not per interface, and the list is deduplicated first, so two interfaces sharing a subnet probe it once rather than twice. A machine with more qualifying interfaces than that stops at the budget and logs it.

After that, the only traffic is to your Core: a WebSocket to port 9330 for the Roon MOO protocol, and HTTP GETs to the same host for album art. Those GETs are made by tonearmd, never by the shell: the daemon caps each image's size and dimensions, strips PNG metadata, keeps the copy in its own runtime directory, and the popup only ever loads that local file.

Nothing leaves your network. There is no telemetry, no analytics, and no outbound connection to anything but your Roon Core.

Zones

The ZONES list at the bottom of the popup does two different things, and they are deliberately separate targets:

Action What it does
Click a zone's name Follow that zone — changes what the widget shows. Clicking the zone you're already pinned to unpins it, so the widget goes back to following whichever zone is playing.
Click the cast icon at the right of a row Move the music there. Roon's queue, the current track and its position all move to that zone.

The cast icon only appears on rows that can actually receive the stream: not on the zone you're already listening to, and not when there's nothing playing. Because it moves the queue rather than the playback state, it works while paused too — pause in the kitchen, move it to the study, press play there.

If you had pinned a zone, the widget re-pins to the destination so it doesn't sit watching the room you just emptied. If you weren't pinned, it follows the music on its own as usual.

From a script: tonearmctl transfer <zone_id>.

There's no keyboard shortcut for this yet — the zone rows aren't part of the popup's keyboard cursor, which currently only covers search results.

Strict pinning (optional)

By default, if a pinned endpoint disappears, Tonearm falls back to another active zone. To keep controls from affecting another room, set the JSON boolean "strict_pins": true in Tonearm's private ~/.config/tonearm/config.json, preserving the other fields. Restart the daemon for the setting to take effect. Do not share this directory: it contains pairing credentials.

With strict pinning enabled, a missing pinned zone leaves no selected zone and its controls are refused. Other zones remain listed, and the saved pin is kept for the endpoint's return. Returning does not start playback or restore volume. Unpinning restores auto-follow. Omit the setting or set it to false to keep the existing fallback. There is no UI or CLI switch for this option.

Remote commands are also refused while the Core is disconnected, regardless of this setting; cached zones are not usable playback targets. This policy does not lock a multi-step operation to one zone if the user changes selection.

Library search

The popup can search your whole Roon library — not just the current zone or the album that's playing. The search field stays hidden until you use it, on purpose, so the popup keeps its normal size when you're just glancing at what's playing; the / search hint on the ZONES line is what tells you it's there, and clicking it opens the field.

To search, open the popup and press / — or just start typing; most printable keys open the field and start your query with that character. Press Enter to submit. Results come back grouped the way Roon's own search groups them: a top match, then Artists, Albums, Composers, Tracks, and Works, each row showing a count.

The exceptions are h, j, k, l, x, X and Space: the Omarchy shell's own panel key handler claims those before any widget sees them (h/j/k/l are vim-style movement, and j/k also double as Down/Up here; x is delete; Space activates). They cannot start a search — press / first and type them into the field.

Key Behavior
/ Focus the search field
Any printable key except h j k l x X and Space Focus the field and start the query with that character
Enter (while typing) Submit the search
↑ / ↓ Move the selection
Enter (on a result) Play if the row is playable, otherwise descend into it (e.g. Albums → its list of albums)
→ Descend into the selected row
← Back one level
Esc Back one level; closes the popup at the top level

Playing a row clears the search and leaves the popup open, so you can pick something else without reopening it. The now-playing card above updates to whatever just started, which is your confirmation it worked.

Play Now is the only action. There's no Queue button and no queue key, because the popup has no way to show you a queue — so queuing would be a control whose effect you could never see. It isn't in the daemon either: Play Now is the only action tonearm invokes.

Settings

Configure these from the widget's settings panel in the Omarchy shell:

Setting Default What it does
Tint the seek bar with the album's color on Derives an accent color from the current track's album art and uses it for the seek bar fill. When off (or when no art is available), the theme's accent color is used instead.

There is deliberately no setting for the album art size or for hiding the volume slider. The art size is derived from your theme's spacing scale so the card stays balanced at any font size, and the volume row hides itself automatically on a zone whose output reports no volume — a switch for that would have been a second way to reach an outcome the widget already gets right.

Media keys

Tonearm publishes an MPRIS2 player (org.mpris.MediaPlayer2.tonearm) on your session D-Bus as soon as it connects to Roon. Omarchy's existing media-key handling picks it up automatically — no changes to your Hyprland config are needed. If multiple players are on the bus at once (a browser tab, a local music player, etc.), your media keys follow whichever your desktop's existing MPRIS arbitration considers active, the same as any other MPRIS player.

The daemon does not get your session bus itself. It reaches it through a filtering proxy, tonearmd-bus.service (xdg-dbus-proxy), that lets it publish this one player name and do nothing else on the bus. xdg-dbus-proxy ships with a stock Omarchy install; if yours lacks it, media keys are unavailable until you install it (omarchy pkg add xdg-dbus-proxy) and re-run setup.sh. Everything else works without it. setup.sh --check tells you which case you are in.

If your Roon Core goes away

Tonearm notices within a few seconds. The bar icon switches to the alert glyph in the error colour, and the popup's header says Roon Core unreachable in place of the Core's name. The popup stops showing a track rather than leaving the last one on screen, because a stale track under an error header is the widget being confidently wrong.

Recovery is automatic — the underlying Roon library retries about every 20 seconds, and tonearm goes back to normal on its own when the Core answers again. There is nothing to restart.

If the problem is your network rather than the Core — a VPN that captures your local subnet, wifi associated but not routing — the header says No route to your network instead. Tonearm works this out by probing your default gateway when a connection fails: if the gateway itself does not answer, the Core is not the thing to go and look at.

Removal

Removing just the plugin folder leaves the user service behind. Remove the service first, then the plugin. The uninstall command checks that the unit belongs to tonearm and preserves your Core address, pairing token and pinned zone for a future reinstall:

# 1. Stop and remove the systemd user service (safe to repeat)
~/.config/omarchy/plugins/ssandys.tonearm/setup.sh --uninstall

# 2. Remove the plugin
omarchy plugin remove ssandys.tonearm      # or ./bin/dev down for a dev deploy

# 3. Optional: clear tonearm's own config, including the Roon pairing token
rm -rf ~/.config/tonearm/

If the plugin folder was already removed, setup.sh is no longer available. Units installed with this version skip starting when the daemon path is missing; older units may still retry with 203/EXEC. In either case, remove the leftover unit manually:

systemctl --user disable --now tonearmd.service
systemctl --user stop tonearmd-bus.service
rm -f ~/.config/systemd/user/tonearmd.service ~/.config/systemd/user/tonearmd-bus.service
systemctl --user daemon-reload

That last step is optional but worth knowing about: ~/.config/tonearm/ holds the Core's host/port, your pairing token, and the pinned zone. If you delete it, reinstalling tonearm later means re-approving the extension in Roon Remote → Settings → Extensions from scratch, the same as a first install. Leaving it in place lets a reinstall pick up where you left off.

You can also disable tonearm from Roon's side at any time, independently of anything above, from Roon Remote → Settings → Extensions.

About

Omarchy shell bar widget for Roon: now-playing, transport, library search, zone switching and transfer. Backed by a Python daemon that speaks Roon's MOO protocol and publishes MPRIS.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages