Omahub
Sign in with GitHub
← All plugins
T

Apple TV Remote

by Thomas Evans

Keyboard-driven remote with discovery, pairing, and device switching

GitHub
Install
$ omarchy plugin add https://github.com/teevans/omarchy-apple-tv-remote --enable
Widgets #bar #quickshell #media

Apple TV Remote for Omarchy

A keyboard-first Apple TV remote for the Omarchy Quattro bar. It discovers and pairs Apple TVs on your local network, remembers multiple devices, and keeps one Companion connection open for responsive controls.

Features

  • Directional navigation, Select, Back, Home, and TV
  • Play/pause, previous, next, and volume controls
  • Wake, sleep, and power status
  • Local-network discovery, PIN pairing, and device switching
  • Mouse and keyboard operation from a theme-aware bar panel

Requirements

  • Omarchy Quattro
  • Python 3.9 or newer with venv support
  • An Apple TV reachable on the same local network
  • Internet access on first launch to install the pinned pyatv dependency into an isolated environment
  • Optional: Avahi's avahi-browse for faster discovery; the plugin falls back to pyatv scanning

The plugin runs unsandboxed inside omarchy-shell. Review the repository before installing it.

Install

omarchy plugin add https://github.com/teevans/omarchy-apple-tv-remote.git --enable

The first launch creates an isolated Python environment under ${XDG_DATA_HOME:-$HOME/.local/share}/io.github.teevans.apple-tv-remote/ and installs pyatv==0.18.0. This can take a moment; the panel will reconnect automatically when setup finishes.

Open the bar widget, choose Devices, select an Apple TV, and enter the four-digit PIN shown on the television. You can also set a preferred Apple TV name and host in the widget settings.

Controls

Key Action
Arrow keys or H/J/K/L Navigate
Enter Select
B Back
G Home screen
T TV button
P Play/pause
- / + Volume
W / S Wake / sleep
D Devices
Escape or Q Close

Update

omarchy plugin update io.github.teevans.apple-tv-remote

Remove

Remove the plugin:

omarchy plugin remove io.github.teevans.apple-tv-remote

Optionally remove its Python environment and remembered device list:

rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/io.github.teevans.apple-tv-remote"
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/apple-tv-remote"

Pairing credentials are stored by pyatv in ~/.pyatv.conf with mode 0600. Other pyatv clients may use the same file, so the uninstall command deliberately leaves it in place. Delete it manually only if you no longer need those credentials.

Development

omarchy plugin validate .
shellcheck apple-tv-remote tests/fake-python tests/test-apple-tv-remote
tests/test-apple-tv-remote

License

MIT