# GTV - Google TV / Android TV Remote Control CLI

A command-line remote control for Android TV and Google TV devices. Uses the **Android TV Remote protocol v2** -- the same protocol the official Google TV mobile app uses. Built with **cmd2** for a rich interactive shell with tab completion, command history, and categorized help.

No ADB or developer mode required. Works over your local network via IP.

## Features

- **Device Discovery** -- Finds Android TV / Google TV devices on your network via mDNS
- **Bluetooth Discovery** -- Scan for nearby Android TV devices via Bluetooth Low Energy
- **Secure Pairing** -- Certificate-based pairing with on-screen PIN (same as the mobile app)
- **Full Remote Control** -- Navigation, media, volume, power, number keys, color keys
- **App Launching** -- YouTube, Netflix, Disney+, Prime Video, and more with shortcuts
- **Deep Links** -- Open any URL or deep link on the TV
- **Tab Completion** -- Complete app names, key codes, and commands with Tab
- **Command History** -- Navigate previous commands with arrow keys
- **Categorized Help** -- Commands organized by function (Navigation, Media, Volume, etc.)
- **One-shot Commands** -- Send a single command without entering interactive mode
- **Async Notifications** -- Real-time device status updates (power, app changes, volume)

## Requirements

- Python 3.9+
- An Android TV / Google TV device on the same network
- The [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) (pre-installed on most devices)

## Installation

From PyPI:

```bash
pip install gtv-remote
```

From source:

```bash
git clone https://github.com/erodriguez/gtv-remote.git
cd gtv-remote
pip install .
```

For development:

```bash
pip install -e .
```

## Project Structure

```
gtv/
├── __init__.py
├── __main__.py
├── cli.py
├── app.py
├── constants.py
├── models.py
├── remote.py
└── discovery/
    ├── __init__.py
    ├── mdns.py
    └── bluetooth.py
```

## Quick Start

```bash
gtv-remote
gtv-remote discover
gtv-remote discover -b
gtv-remote pair 192.168.1.100
gtv-remote connect 192.168.1.100
```

## Usage

### Discover Devices

```bash
gtv-remote discover
gtv-remote discover --timeout 10
gtv-remote discover -b
gtv-remote discover -b -a
```

### Pair with a Device

Pairing is required once per device. A PIN code will appear on your TV screen.

```bash
gtv-remote pair
gtv-remote pair 192.168.1.100
```

Certificates are stored in `~/.config/gtv/`.

### Interactive Remote Control

```bash
gtv-remote
gtv-remote connect
gtv-remote connect 192.168.1.100
```

Once connected, the prompt shows the device IP and power state:

```
gtv (192.168.1.100 [on])> _
```

Type `help` to see all commands organized by category:

```
Apps & Input        app, key, open
Connection          connect, disconnect, discover, pair
Device Info         apps, keys, status
Media               play, pause, playpause, stop, next, prev, rewind, ff, ...
Navigation          up, down, left, right, enter, back, home, menu, ...
Number Keys         0-9, red, green, yellow, blue
Volume & Power      volup, voldown, mute, power
```

### Command Reference

| Command | Action |
|---------|--------|
| **Navigation** | |
| `up` `down` `left` `right` | D-pad navigation |
| `enter` / `select` / `ok` | Confirm selection |
| `back` | Go back |
| `home` | Home screen |
| `menu` | Open menu |
| `settings` | Open settings |
| `search` | Open search |
| `assist` | Google Assistant |
| **Media** | |
| `play` `pause` `playpause` | Media playback |
| `stop` `next` `prev` | Track control |
| `rewind` `ff` | Seek |
| `captions` | Toggle subtitles |
| `chup` `chdown` | Channel up/down |
| **Volume & Power** | |
| `volup [N]` | Volume up (optionally N times) |
| `voldown [N]` | Volume down (optionally N times) |
| `mute` | Toggle mute |
| `power` | Power on/off |
| **Apps** | |
| `app youtube` | Launch YouTube |
| `app netflix` | Launch Netflix |
| `app disney` | Launch Disney+ |
| `app prime` | Launch Prime Video |
| `app <package.id>` | Launch any app by package |
| `open <url>` | Open a deep link |
| `apps` | List all app shortcuts |
| **Input** | |
| `key DPAD_UP` | Send raw remote key |
| `keys` | List all key codes |
| **Info** | |
| `status` | Show device info |
| `discover` | Re-scan for devices |

### Tab Completion

Press **Tab** to auto-complete:
- Command names
- App shortcut names (after `app `)
- Raw key codes (after `key `)

### One-Shot Commands

```bash
gtv-remote send --host 192.168.1.100 home
gtv-remote send --host 192.168.1.100 volup
gtv-remote send --host 192.168.1.100 playpause
gtv-remote send --host 192.168.1.100 app youtube
gtv-remote send --host 192.168.1.100 key POWER
```

### Device Status

```bash
gtv-remote status --host 192.168.1.100
```

## App Shortcuts

| Shortcut | App |
|----------|-----|
| `youtube` | YouTube |
| `netflix` | Netflix |
| `disney` | Disney+ |
| `prime` / `amazon` | Prime Video |
| `kodi` | Kodi |
| `plex` | Plex |
| `hbo` | HBO Max |
| `hulu` | Hulu |
| `spotify` | Spotify |
| `twitch` | Twitch |
| `appletv` | Apple TV |
| `crunchyroll` | Crunchyroll |
| `browser` | Web Browser |

You can also launch any app by its package name: `app com.example.myapp`

## Troubleshooting

- **No devices found**: Make sure your TV is on and connected to the same Wi-Fi network
- **Authentication failed**: Run `pair` to re-pair with the device
- **Connection refused**: Ensure the Android TV Remote Service is installed (Settings > Apps > Show system apps)
- **Pairing code not appearing**: Restart the Android TV Remote Service or reboot the TV

## How It Works

This tool uses the `androidtvremote2` Python library which implements the Android TV Remote Control protocol v2. This is the same TLS-encrypted protocol used by the official Google TV mobile app. Communication happens over TCP ports 6466 (pairing) and 6467 (remote control). Device discovery uses mDNS (Zeroconf) to find `_androidtvremote2._tcp.local.` services. Bluetooth LE scanning uses `bleak` to detect nearby Android TV devices by name patterns and manufacturer data.
