hub / github.com/drosoCode/atvremote

github.com/drosoCode/atvremote @v0.1.3

Chat with this repo

repository ↗ · DeepWiki ↗ · release v0.1.3 ↗ · + Follow

373 symbols 495 edges 14 files 75 documented · 20%

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

Android TV remote

About this project

This tool implements the remote control protocol for Android TV and Google TV.

The v1 is for the old Android TV Remote Control app

The v2 is for the newer Google TV app used when your android tv's remote services version is >= 5

The anymote protocol (old protocol for google tv < 2014) is not supported.

Quickstart

Check on your android tv device the Remote Services version (in Settings > Apps > See all apps > Android TV Remote Service). If the version is >= 5, you sould use the v2 protocol.

First, start the pairing process ./atvremote -ip="192.168.1.20" -version=2 -pair

Then, you can send a list of keypress like this (this sould open the settings) ./atvremote -ip="192.168.1.20" -version=2 command="HOME;HOME;UP;RIGHT;RIGHT;ENTER

Usage

You can use this project as a library (see the godoc page) or directly in cli (see the releases page). In CLI mode, you must at least specify the IP to your android tv box. Here is the list of the supported flags:

Name	Required	Default	Description	Example
pair	No	False	Pairing mode (if not specified the tool will start in command mode and assume that the pairing have already been done)	`-pair`
ip	Yes	None	IP or hostname of your android tv device	`-ip="192.168.1.20"`
cert	No	`./cert.pem`	Path to your certificate file (will be created in pairing mode)	`-cert="./cert.pem"`
key	No	`./key.pem`	Path to your private key file (will be created in pairing mode)	`-key="./key.pem"`
version	No	`1`	Protocol version	`-version=1`
command	No	None	List of keypress to emulate (see below)	`-command="HOME;HOME;UP;RIGHT;RIGHT;ENTER"`
open	No	None	Open an app using an intent (V1 Only)	`-open="com.netflix.ninja/.MainActivity"`
link	No	None	Open a link (V2 Only)	`-open="https://netflix.com/title/"`
info	No	None	Print a json object of the device's infos (V2 Only)	`-info`

Additional information

Command flag: a string with alphanumeric characters will automaticaly be converted to keypresses. You can also send some specific keypresses defined in pkg/common/types.go prefixed with KEYCODE_ and separated with semicolons. There are some shortcuts for the most common keys (UP, DOWN, LEFT, RIGHT, HOME, BACK, VOLP, VOLM, MUTE, PWR, ENTER). For examle this string a;UP;bc;KEYCODE_TV_INPUT_HDMI_1 will be parsed as [RemoteKeyCode_KEYCODE_A, RemoteKeyCode_KEYCODE_DPAD_UP, RemoteKeyCode_KEYCODE_B, RemoteKeyCode_KEYCODE_C, KEYCODE_TV_INPUT_HDMI_1] (see pkg/common/parsekey.go for more info).
Open flag: an activity in in the format yourpackagename/.activityname.
Link flag: You can start an app using a deeplink defined in its appmanifest (like described here). By default, if no deeplink is found, the link will open in a browser.

Acknowledgments

This project wouldn't have been possible without these awesome projects which reverse-engineered these protocols. - Aymkdn's wiki on the protocols V1 and V2 - louis49's androidtv-remote js implementation (especially for the v2 proto files)

Core symbols most depended-on inside this repo

write

called by 6

pkg/v2/command/command.go

readMessage

called by 4

pkg/v2/pairing/pairing.go

write

called by 4

pkg/v2/pairing/pairing.go

Connect

called by 4

pkg/v2/pairing/pairing.go

send

called by 4

pkg/v1/pairing/pairing.go

read

called by 4

pkg/v1/pairing/pairing.go

read

called by 3

pkg/v1/command/command.go

Secret

called by 2

pkg/v2/pairing/pairing.go

Shape

Method 301

Struct 46

Function 20

TypeAlias 6

Languages

Go100%

Modules by API surface

pkg/v2/proto/remotemessage.pb.go222 symbols

pkg/v2/proto/pairingmessage.pb.go101 symbols

pkg/v2/command/command.go12 symbols

pkg/v1/command/command.go8 symbols

pkg/v2/pairing/pairing.go7 symbols

pkg/v1/pairing/pairing.go7 symbols

pkg/v1/pairing/types.go6 symbols

cmd/flags.go3 symbols

cmd/main.go2 symbols

pkg/common/types.go1 symbols

pkg/common/secret.go1 symbols

pkg/common/parsekey.go1 symbols

For agents

$ claude mcp add atvremote \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact