gtv-remote 0.2.1

Google TV / Android TV Remote Control CLI

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 (pre-installed on most devices)

Installation

From PyPI:

pip install gtv-remote

From source:

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

For development:

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

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

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.

gtv-remote pair
gtv-remote pair 192.168.1.100

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

Interactive Remote Control

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

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

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.