Itsytv

A native macOS menu bar app for controlling your Apple TV.

Also on iPhone

Itsytv is now available on iOS with the same core experience plus features designed for mobile:

• TMDB lookup for what's playing – poster art, ratings, and details for movies and TV shows
• Ergonomic design for left- and right-handed use

  

Features

• Menu bar remote – control your Apple TV from a compact floating panel
• D-pad and buttons – circular d-pad with directional navigation, select, home, menu/back, play/pause
• Keyboard navigation – arrow keys, Return, Backspace, Escape, Space mapped to remote buttons
• Text input – type directly into Apple TV text fields with a live keyboard
• Now playing – artwork, title, artist, progress bar, and playback controls
• App launcher – grid of installed apps with icons fetched from the App Store; drag to reorder
• Multiple devices – pair and switch between multiple Apple TVs
• Global hotkeys – assign keyboard shortcuts to instantly open the remote for specific Apple TVs
• Per-device panel position – remembers where you placed the remote for each Apple TV
• Launch at login – optional auto-start from the menu bar
• Unpair – remove pairing credentials from the panel menu

Perfect companion to Itsyhome

Itsytv pairs naturally with Itsyhome – a free macOS menu bar app for controlling your HomeKit devices. Manage lights, cameras, thermostats, locks, scenes, and 18+ accessory types without ever opening the Home app.

Install

brew install --cask itsytv

Or download the latest DMG from GitHub releases.

Troubleshooting

Apple TV doesn't show a PIN code when pairing

If you send a pairing request but no PIN appears on your TV screen, your Apple TV is likely restricting which devices can connect to it. To fix this:

1. Open Settings > AirPlay and Apple Home on your Apple TV
2. Set Allow access to Anyone on the same network
3. Go to Settings > General > Restrictions
4. Set both AirPlay Settings and Remote App Pairing to Allow

This setting needs to stay on this value for itsytv to maintain a connection to your Apple TV.

Remote disappears after a few seconds

If the remote panel closes on its own shortly after connecting, your Apple TV's AirPlay access setting is likely set to Only people sharing this home. Open Settings on your Apple TV, go to AirPlay and Apple Home, and change Allow access to Anyone on the same network.

Nothing happens when I launch the app

Itsytv is a menu bar app – it lives in the top-right area of your screen as a small TV icon, not in the Dock. On MacBooks with a notch, macOS hides menu bar icons that don't fit behind the notch – silently, with no warning. If your menu bar is crowded, the itsytv icon may be there but invisible.

To fix this, hold Cmd and drag any icons you don't need off the menu bar. Once itsytv appears, Cmd-drag it to the right so it stays visible.

Architecture

This app is a thin macOS UI layer on top of itsytv-core – a Swift package that implements the Apple TV Companion Link and AirPlay protocols. The same core powers both the macOS and iOS apps.

itsytv-macos/
├── itsytvApp.swift              # App entry point
├── UI/
│   ├── AppController.swift      # NSStatusItem, menu, floating panel, keyboard monitor
│   ├── MenuBarView.swift        # SwiftUI views: remote, now playing, app grid
│   └── AppIconLoader.swift      # App icons from iTunes Lookup API
├── DesignSystem/
│   ├── DesignSystem.swift       # Colours, typography, spacing, sizing tokens
│   └── HighlightingMenuItemView.swift
├── AppIntents/
│   └── OpenRemoteIntent.swift   # Shortcuts action to open the remote for a specific Apple TV
├── MRP/
│   └── Proto/                   # Protobuf definitions (.proto files)
└── Utilities/
    ├── UpdateChecker.swift      # GitHub release checker
    └── HotkeyManager.swift      # Global hotkey registration

All protocol, crypto, discovery, and device management code lives in itsytv-core.

Requirements

• macOS 14.0 or later
• Xcode 16.0 or later
• XcodeGen for project generation
• Apple TV running tvOS 15 or later on the same local network

Setup

1. Clone the repositories

git clone https://github.com/nickustinov/itsytv-macos.git
git clone https://github.com/nickustinov/itsytv-core.git

Both repositories must be side by side – the Xcode project references ../itsytv-core as a local Swift package.

2. Install XcodeGen

brew install xcodegen

3. Generate the Xcode project

cd itsytv-macos
xcodegen generate

4. Open and run

open itsytv.xcodeproj

Select the itsytv scheme and run.

Building

The project uses XcodeGen to generate the Xcode project from project.yml. After making changes to project configuration:

xcodegen generate

Releasing

1. Bump MARKETING_VERSION and CURRENT_PROJECT_VERSION in project.yml
2. Update CHANGELOG.md
3. Build, sign, and package the DMG:

bash scripts/build-release.sh

4. Notarize and staple:

xcrun notarytool submit dist/Itsytv-<VERSION>.dmg \
    --apple-id <APPLE_ID> --team-id <TEAM_ID> \
    --password <APP_SPECIFIC_PASSWORD> --wait
xcrun stapler staple dist/Itsytv-<VERSION>.dmg

5. Create the GitHub release:

gh release create v<VERSION> dist/Itsytv-<VERSION>.dmg \
    --title "v<VERSION>" --notes "Release notes here"

6. Homebrew cask – itsytv is in the official homebrew-cask repository with autobump enabled. BrewTestBot automatically detects new GitHub releases and opens a PR within ~3 hours. No manual action needed.

License

MIT License (c) 2026 Nick Ustinov – see LICENSE for details.

Author

Nick Ustinov – @nickustinov

Acknowledgements

Protocol implementation informed by pyatv, the comprehensive Python library for Apple TV control.