GTV Desktop Remote

A macOS desktop remote for Google TV and Android TV devices.
Discover, pair once, and control your TV from your Mac — with keyboard support.

---

Overview

GTV Desktop Remote lets you control any Google TV or Android TV device from your Mac. It runs as a menubar app — always one keystroke away — and uses the same encrypted pairing protocol as the official Android TV Remote app.

• Network scan — discovers compatible devices on your local network automatically
• One-time pairing — enter a 6-digit code once; credentials are saved securely
• Full remote control — navigation, select, home, back, play/pause, volume, power
• Keyboard control — drive your TV from the keyboard without touching the mouse
• Text input — send text directly to apps that support Android TV text entry
• IP-change resilient — device identity is tracked by MAC address, not IP, so re-pairing is never needed when your TV's IP changes
• Global shortcut — CmdOrCtrl+Shift+G shows or hides the remote from anywhere

---

Screenshots

Remote controls

Device management

---

Installation

Download the latest .dmg from the Releases page, open it, and drag the app to your Applications folder.

If you install from the .dmg, macOS may block the app on first launch because it was downloaded from the internet. If that happens:

1. Open System Settings → Privacy & Security.
2. Scroll to the Security section.
3. Click Open Anyway for GTV Remote.
4. Confirm the prompt and launch the app again.

Or install with Homebrew:

brew install --cask usrivastava92/tap/gtv-desktop-remote

The Homebrew cask removes the quarantine flag automatically during install and prints fallback steps if macOS still blocks launch.

Requirement: macOS. Your TV must have Android TV Remote Service enabled and be on the same local network as your Mac.

---

Getting Started

1. Launch the app — it appears in your menu bar.
2. The app scans your network for compatible devices.
3. Select your TV from the device list.
4. If not yet paired, click Start Pairing and enter the 6-character code shown on your TV.
5. Once paired, click Connect — you're ready to use the remote.

The app remembers paired devices, so future connections are instant.

---

Keyboard Shortcuts

When the remote is focused and connected, your keyboard controls the TV directly:

Key	Action
↑ ↓ ← →	Navigate
Enter	Select / OK
Escape / Backspace	Back
H	Home
Space / K	Play / Pause
+ / =	Volume Up
- / _	Volume Down
P	Power

Cmd, Ctrl, and Option combinations are ignored so they don't interfere with normal macOS shortcuts.

Global shortcut: CmdOrCtrl+Shift+G — show or hide the remote from any app.

---

Troubleshooting

TV not appearing in the scan?

• Confirm the TV and Mac are on the same Wi-Fi network.
• Confirm Android TV Remote Service is enabled on the TV.
• Try re-running the network scan.

Pairing not completing?

• Start a fresh pairing session and enter the latest code shown on the TV screen.
• If the device was previously saved, remove it and pair again.

App not opening or only showing the menubar icon?

• If macOS blocks launch, use System Settings → Privacy & Security → Open Anyway.
• If the menubar icon appears but the window does not, click the menubar icon or press Cmd+Shift+G.
• If it still fails, attach the app log from ~/Library/Application Support/GTV Remote/gtv-remote.log to your issue.
• Also include your macOS version, Mac model/processor, install method (.dmg, Homebrew, or source), and whether the menubar icon appears.

---

For Developers

Development setup, packaging, debug telemetry, and local build workflows are documented in DEVELOPMENT.md.