Apple TV Remote

A native macOS remote for Apple TV.

Apple TV Remote is built for people who want a small desktop remote: discover an Apple TV on your local network, pair once, then use a touchpad-style control surface, keyboard shortcuts, playback controls, text entry, and power controls from macOS.

This project is pre-release. It is usable from source, but behavior can vary by Apple TV model, tvOS version, network permissions, and HDMI-CEC setup.

Install

The current release is unsigned. macOS may show a Gatekeeper warning the first time you open it.

1. Download the latest Apple.TV.Remote.app.zip from Releases.
2. Unzip it.
3. Move Apple TV Remote.app to /Applications.
4. Open Apple TV Remote.app.

If macOS blocks the app because it is unsigned, remove quarantine metadata after unzipping:

xattr -cr "Apple TV Remote.app"

Then open it again.

Build From Source

Use this path if you prefer to build locally.

Requirements:

• macOS 13 or newer
• Python 3.7 or newer
• Xcode Command Line Tools

Install Command Line Tools if needed:

xcode-select --install

Build the app:

git clone https://github.com/sewatson/apple-tv-remote.git
cd apple-tv-remote
./build.sh

Launch it:

open "Apple TV Remote.app"

Optional: install into Applications:

cp -r "Apple TV Remote.app" /Applications/

See docs/RELEASE.md for release and unsigned build notes.

First Run

1. Open Apple TV Remote.app.
2. Click the device picker.
3. Select your Apple TV.
4. Enter the PIN shown on your Apple TV when prompted.

After pairing, credentials are stored locally by pyatv and the app will try to reconnect on future launches.

Pairing credentials live at:

~/.appletv_remote/pyatv_storage.json

Delete that file to reset pairing.

Use

• Swipe on the touchpad to navigate.
• Tap the touchpad to select.
• Use Menu/Back to go back.
• Use Home to return to the Apple TV home screen.
• Use Play/Pause when playback controls are available.
• Use the keyboard button for text entry.
• Use the power button to wake or sleep the device.

Keyboard Shortcuts

Movement:

• Arrow keys
• WASD

Actions:

• Select: F or Return
• Menu: Q or /
• Home: E or .
• Play/Pause: Space
• Power On: ⌘O
• Power Off: ⌘P

Standard macOS shortcuts such as ⌘Q, ⌘W, and ⌘, are preserved.

Troubleshooting

No devices found

• Make sure your Mac and Apple TV are on the same network.
• Confirm macOS Local Network permission is allowed.
• Wake the Apple TV and try discovery again.

Pairing does not work

• Check that you entered the correct PIN.
• Reset local pairing:

rm -f ~/.appletv_remote/pyatv_storage.json

Commands do not work

• Rebuild with ./build.sh.
• Re-pair if needed.
• Confirm the selected Apple TV is awake and reachable.

App will not open

xattr -cr "Apple TV Remote.app"

Privacy

Apple TV Remote does not include telemetry, analytics, or intentional communication outside your local network. It uses pyatv to discover and control Apple TV devices locally.

See PRIVACY.md for details.

Builders and Contributors

Developer documentation lives in docs/DEVELOPMENT.md. Product scope and architecture live in docs/SPEC.md.

Credits

• pyatv by Pierre Ståhl: https://github.com/postlund/pyatv
• Third-party notices are listed in THIRD_PARTY_NOTICES.md.

Apple, Apple TV, macOS, Swift, and SwiftUI are trademarks of Apple Inc. This project is not affiliated with or endorsed by Apple Inc.

License

MIT. See LICENSE.