gtv-remote 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. gtv_remote-0.1.0/LICENSE +21 -0
  2. gtv_remote-0.1.0/PKG-INFO +250 -0
  3. gtv_remote-0.1.0/README.md +215 -0
  4. gtv_remote-0.1.0/gtv/__init__.py +1 -0
  5. gtv_remote-0.1.0/gtv/__main__.py +3 -0
  6. gtv_remote-0.1.0/gtv/app.py +614 -0
  7. gtv_remote-0.1.0/gtv/cli.py +65 -0
  8. gtv_remote-0.1.0/gtv/constants.py +103 -0
  9. gtv_remote-0.1.0/gtv/discovery/__init__.py +4 -0
  10. gtv_remote-0.1.0/gtv/discovery/bluetooth.py +54 -0
  11. gtv_remote-0.1.0/gtv/discovery/mdns.py +70 -0
  12. gtv_remote-0.1.0/gtv/models.py +23 -0
  13. gtv_remote-0.1.0/gtv/remote.py +76 -0
  14. gtv_remote-0.1.0/gtv_remote.egg-info/PKG-INFO +250 -0
  15. gtv_remote-0.1.0/gtv_remote.egg-info/SOURCES.txt +19 -0
  16. gtv_remote-0.1.0/gtv_remote.egg-info/dependency_links.txt +1 -0
  17. gtv_remote-0.1.0/gtv_remote.egg-info/entry_points.txt +2 -0
  18. gtv_remote-0.1.0/gtv_remote.egg-info/requires.txt +7 -0
  19. gtv_remote-0.1.0/gtv_remote.egg-info/top_level.txt +1 -0
  20. gtv_remote-0.1.0/pyproject.toml +58 -0
  21. gtv_remote-0.1.0/setup.cfg +4 -0
gtv_remote-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Eduardo Rodriguez
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
gtv_remote-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,250 @@
1
+ Metadata-Version: 2.4
2
+ Name: gtv-remote
3
+ Version: 0.1.0
4
+ Summary: Google TV / Android TV Remote Control CLI
5
+ Author: Eduardo Rodriguez
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/erodriguez/gtv-remote
8
+ Project-URL: Repository, https://github.com/erodriguez/gtv-remote
9
+ Project-URL: Issues, https://github.com/erodriguez/gtv-remote/issues
10
+ Keywords: google-tv,android-tv,remote-control,cli,chromecast,androidtvremote2,bluetooth
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Home Automation
22
+ Classifier: Topic :: Multimedia
23
+ Classifier: Topic :: Utilities
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: androidtvremote2>=0.0.13
28
+ Requires-Dist: zeroconf>=0.131.0
29
+ Requires-Dist: cmd2>=2.4.0
30
+ Requires-Dist: aiofiles>=0.8
31
+ Requires-Dist: cryptography>=3
32
+ Requires-Dist: protobuf>=4.21
33
+ Requires-Dist: bleak>=0.21.0
34
+ Dynamic: license-file
35
+
36
+ # GTV - Google TV / Android TV Remote Control CLI
37
+
38
+ 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.
39
+
40
+ No ADB or developer mode required. Works over your local network via IP.
41
+
42
+ ## Features
43
+
44
+ - **Device Discovery** -- Finds Android TV / Google TV devices on your network via mDNS
45
+ - **Bluetooth Discovery** -- Scan for nearby Android TV devices via Bluetooth Low Energy
46
+ - **Secure Pairing** -- Certificate-based pairing with on-screen PIN (same as the mobile app)
47
+ - **Full Remote Control** -- Navigation, media, volume, power, number keys, color keys
48
+ - **App Launching** -- YouTube, Netflix, Disney+, Prime Video, and more with shortcuts
49
+ - **Deep Links** -- Open any URL or deep link on the TV
50
+ - **Tab Completion** -- Complete app names, key codes, and commands with Tab
51
+ - **Command History** -- Navigate previous commands with arrow keys
52
+ - **Categorized Help** -- Commands organized by function (Navigation, Media, Volume, etc.)
53
+ - **One-shot Commands** -- Send a single command without entering interactive mode
54
+ - **Async Notifications** -- Real-time device status updates (power, app changes, volume)
55
+
56
+ ## Requirements
57
+
58
+ - Python 3.9+
59
+ - An Android TV / Google TV device on the same network
60
+ - The [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) (pre-installed on most devices)
61
+
62
+ ## Installation
63
+
64
+ From PyPI:
65
+
66
+ ```bash
67
+ pip install gtv-remote
68
+ ```
69
+
70
+ From source:
71
+
72
+ ```bash
73
+ git clone https://github.com/erodriguez/gtv-remote.git
74
+ cd gtv-remote
75
+ pip install .
76
+ ```
77
+
78
+ For development:
79
+
80
+ ```bash
81
+ pip install -e .
82
+ ```
83
+
84
+ ## Project Structure
85
+
86
+ ```
87
+ gtv/
88
+ ├── __init__.py
89
+ ├── __main__.py
90
+ ├── cli.py
91
+ ├── app.py
92
+ ├── constants.py
93
+ ├── models.py
94
+ ├── remote.py
95
+ └── discovery/
96
+ ├── __init__.py
97
+ ├── mdns.py
98
+ └── bluetooth.py
99
+ ```
100
+
101
+ ## Quick Start
102
+
103
+ ```bash
104
+ gtv-remote
105
+ gtv-remote discover
106
+ gtv-remote discover -b
107
+ gtv-remote pair 192.168.1.100
108
+ gtv-remote connect 192.168.1.100
109
+ ```
110
+
111
+ ## Usage
112
+
113
+ ### Discover Devices
114
+
115
+ ```bash
116
+ gtv-remote discover
117
+ gtv-remote discover --timeout 10
118
+ gtv-remote discover -b
119
+ gtv-remote discover -b -a
120
+ ```
121
+
122
+ ### Pair with a Device
123
+
124
+ Pairing is required once per device. A PIN code will appear on your TV screen.
125
+
126
+ ```bash
127
+ gtv-remote pair
128
+ gtv-remote pair 192.168.1.100
129
+ ```
130
+
131
+ Certificates are stored in `~/.config/gtv/`.
132
+
133
+ ### Interactive Remote Control
134
+
135
+ ```bash
136
+ gtv-remote
137
+ gtv-remote connect
138
+ gtv-remote connect 192.168.1.100
139
+ ```
140
+
141
+ Once connected, the prompt shows the device IP and power state:
142
+
143
+ ```
144
+ gtv (192.168.1.100 [on])> _
145
+ ```
146
+
147
+ Type `help` to see all commands organized by category:
148
+
149
+ ```
150
+ Apps & Input app, key, open
151
+ Connection connect, disconnect, discover, pair
152
+ Device Info apps, keys, status
153
+ Media play, pause, playpause, stop, next, prev, rewind, ff, ...
154
+ Navigation up, down, left, right, enter, back, home, menu, ...
155
+ Number Keys 0-9, red, green, yellow, blue
156
+ Volume & Power volup, voldown, mute, power
157
+ ```
158
+
159
+ ### Command Reference
160
+
161
+ | Command | Action |
162
+ |---------|--------|
163
+ | **Navigation** | |
164
+ | `up` `down` `left` `right` | D-pad navigation |
165
+ | `enter` / `select` / `ok` | Confirm selection |
166
+ | `back` | Go back |
167
+ | `home` | Home screen |
168
+ | `menu` | Open menu |
169
+ | `settings` | Open settings |
170
+ | `search` | Open search |
171
+ | `assist` | Google Assistant |
172
+ | **Media** | |
173
+ | `play` `pause` `playpause` | Media playback |
174
+ | `stop` `next` `prev` | Track control |
175
+ | `rewind` `ff` | Seek |
176
+ | `captions` | Toggle subtitles |
177
+ | `chup` `chdown` | Channel up/down |
178
+ | **Volume & Power** | |
179
+ | `volup [N]` | Volume up (optionally N times) |
180
+ | `voldown [N]` | Volume down (optionally N times) |
181
+ | `mute` | Toggle mute |
182
+ | `power` | Power on/off |
183
+ | **Apps** | |
184
+ | `app youtube` | Launch YouTube |
185
+ | `app netflix` | Launch Netflix |
186
+ | `app disney` | Launch Disney+ |
187
+ | `app prime` | Launch Prime Video |
188
+ | `app <package.id>` | Launch any app by package |
189
+ | `open <url>` | Open a deep link |
190
+ | `apps` | List all app shortcuts |
191
+ | **Input** | |
192
+ | `key DPAD_UP` | Send raw remote key |
193
+ | `keys` | List all key codes |
194
+ | **Info** | |
195
+ | `status` | Show device info |
196
+ | `discover` | Re-scan for devices |
197
+
198
+ ### Tab Completion
199
+
200
+ Press **Tab** to auto-complete:
201
+ - Command names
202
+ - App shortcut names (after `app `)
203
+ - Raw key codes (after `key `)
204
+
205
+ ### One-Shot Commands
206
+
207
+ ```bash
208
+ gtv-remote send --host 192.168.1.100 home
209
+ gtv-remote send --host 192.168.1.100 volup
210
+ gtv-remote send --host 192.168.1.100 playpause
211
+ gtv-remote send --host 192.168.1.100 app youtube
212
+ gtv-remote send --host 192.168.1.100 key POWER
213
+ ```
214
+
215
+ ### Device Status
216
+
217
+ ```bash
218
+ gtv-remote status --host 192.168.1.100
219
+ ```
220
+
221
+ ## App Shortcuts
222
+
223
+ | Shortcut | App |
224
+ |----------|-----|
225
+ | `youtube` | YouTube |
226
+ | `netflix` | Netflix |
227
+ | `disney` | Disney+ |
228
+ | `prime` / `amazon` | Prime Video |
229
+ | `kodi` | Kodi |
230
+ | `plex` | Plex |
231
+ | `hbo` | HBO Max |
232
+ | `hulu` | Hulu |
233
+ | `spotify` | Spotify |
234
+ | `twitch` | Twitch |
235
+ | `appletv` | Apple TV |
236
+ | `crunchyroll` | Crunchyroll |
237
+ | `browser` | Web Browser |
238
+
239
+ You can also launch any app by its package name: `app com.example.myapp`
240
+
241
+ ## Troubleshooting
242
+
243
+ - **No devices found**: Make sure your TV is on and connected to the same Wi-Fi network
244
+ - **Authentication failed**: Run `pair` to re-pair with the device
245
+ - **Connection refused**: Ensure the Android TV Remote Service is installed (Settings > Apps > Show system apps)
246
+ - **Pairing code not appearing**: Restart the Android TV Remote Service or reboot the TV
247
+
248
+ ## How It Works
249
+
250
+ 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.
gtv_remote-0.1.0/README.md ADDED
@@ -0,0 +1,215 @@
1
+ # GTV - Google TV / Android TV Remote Control CLI
2
+
3
+ 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.
4
+
5
+ No ADB or developer mode required. Works over your local network via IP.
6
+
7
+ ## Features
8
+
9
+ - **Device Discovery** -- Finds Android TV / Google TV devices on your network via mDNS
10
+ - **Bluetooth Discovery** -- Scan for nearby Android TV devices via Bluetooth Low Energy
11
+ - **Secure Pairing** -- Certificate-based pairing with on-screen PIN (same as the mobile app)
12
+ - **Full Remote Control** -- Navigation, media, volume, power, number keys, color keys
13
+ - **App Launching** -- YouTube, Netflix, Disney+, Prime Video, and more with shortcuts
14
+ - **Deep Links** -- Open any URL or deep link on the TV
15
+ - **Tab Completion** -- Complete app names, key codes, and commands with Tab
16
+ - **Command History** -- Navigate previous commands with arrow keys
17
+ - **Categorized Help** -- Commands organized by function (Navigation, Media, Volume, etc.)
18
+ - **One-shot Commands** -- Send a single command without entering interactive mode
19
+ - **Async Notifications** -- Real-time device status updates (power, app changes, volume)
20
+
21
+ ## Requirements
22
+
23
+ - Python 3.9+
24
+ - An Android TV / Google TV device on the same network
25
+ - The [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) (pre-installed on most devices)
26
+
27
+ ## Installation
28
+
29
+ From PyPI:
30
+
31
+ ```bash
32
+ pip install gtv-remote
33
+ ```
34
+
35
+ From source:
36
+
37
+ ```bash
38
+ git clone https://github.com/erodriguez/gtv-remote.git
39
+ cd gtv-remote
40
+ pip install .
41
+ ```
42
+
43
+ For development:
44
+
45
+ ```bash
46
+ pip install -e .
47
+ ```
48
+
49
+ ## Project Structure
50
+
51
+ ```
52
+ gtv/
53
+ ├── __init__.py
54
+ ├── __main__.py
55
+ ├── cli.py
56
+ ├── app.py
57
+ ├── constants.py
58
+ ├── models.py
59
+ ├── remote.py
60
+ └── discovery/
61
+ ├── __init__.py
62
+ ├── mdns.py
63
+ └── bluetooth.py
64
+ ```
65
+
66
+ ## Quick Start
67
+
68
+ ```bash
69
+ gtv-remote
70
+ gtv-remote discover
71
+ gtv-remote discover -b
72
+ gtv-remote pair 192.168.1.100
73
+ gtv-remote connect 192.168.1.100
74
+ ```
75
+
76
+ ## Usage
77
+
78
+ ### Discover Devices
79
+
80
+ ```bash
81
+ gtv-remote discover
82
+ gtv-remote discover --timeout 10
83
+ gtv-remote discover -b
84
+ gtv-remote discover -b -a
85
+ ```
86
+
87
+ ### Pair with a Device
88
+
89
+ Pairing is required once per device. A PIN code will appear on your TV screen.
90
+
91
+ ```bash
92
+ gtv-remote pair
93
+ gtv-remote pair 192.168.1.100
94
+ ```
95
+
96
+ Certificates are stored in `~/.config/gtv/`.
97
+
98
+ ### Interactive Remote Control
99
+
100
+ ```bash
101
+ gtv-remote
102
+ gtv-remote connect
103
+ gtv-remote connect 192.168.1.100
104
+ ```
105
+
106
+ Once connected, the prompt shows the device IP and power state:
107
+
108
+ ```
109
+ gtv (192.168.1.100 [on])> _
110
+ ```
111
+
112
+ Type `help` to see all commands organized by category:
113
+
114
+ ```
115
+ Apps & Input app, key, open
116
+ Connection connect, disconnect, discover, pair
117
+ Device Info apps, keys, status
118
+ Media play, pause, playpause, stop, next, prev, rewind, ff, ...
119
+ Navigation up, down, left, right, enter, back, home, menu, ...
120
+ Number Keys 0-9, red, green, yellow, blue
121
+ Volume & Power volup, voldown, mute, power
122
+ ```
123
+
124
+ ### Command Reference
125
+
126
+ | Command | Action |
127
+ |---------|--------|
128
+ | **Navigation** | |
129
+ | `up` `down` `left` `right` | D-pad navigation |
130
+ | `enter` / `select` / `ok` | Confirm selection |
131
+ | `back` | Go back |
132
+ | `home` | Home screen |
133
+ | `menu` | Open menu |
134
+ | `settings` | Open settings |
135
+ | `search` | Open search |
136
+ | `assist` | Google Assistant |
137
+ | **Media** | |
138
+ | `play` `pause` `playpause` | Media playback |
139
+ | `stop` `next` `prev` | Track control |
140
+ | `rewind` `ff` | Seek |
141
+ | `captions` | Toggle subtitles |
142
+ | `chup` `chdown` | Channel up/down |
143
+ | **Volume & Power** | |
144
+ | `volup [N]` | Volume up (optionally N times) |
145
+ | `voldown [N]` | Volume down (optionally N times) |
146
+ | `mute` | Toggle mute |
147
+ | `power` | Power on/off |
148
+ | **Apps** | |
149
+ | `app youtube` | Launch YouTube |
150
+ | `app netflix` | Launch Netflix |
151
+ | `app disney` | Launch Disney+ |
152
+ | `app prime` | Launch Prime Video |
153
+ | `app <package.id>` | Launch any app by package |
154
+ | `open <url>` | Open a deep link |
155
+ | `apps` | List all app shortcuts |
156
+ | **Input** | |
157
+ | `key DPAD_UP` | Send raw remote key |
158
+ | `keys` | List all key codes |
159
+ | **Info** | |
160
+ | `status` | Show device info |
161
+ | `discover` | Re-scan for devices |
162
+
163
+ ### Tab Completion
164
+
165
+ Press **Tab** to auto-complete:
166
+ - Command names
167
+ - App shortcut names (after `app `)
168
+ - Raw key codes (after `key `)
169
+
170
+ ### One-Shot Commands
171
+
172
+ ```bash
173
+ gtv-remote send --host 192.168.1.100 home
174
+ gtv-remote send --host 192.168.1.100 volup
175
+ gtv-remote send --host 192.168.1.100 playpause
176
+ gtv-remote send --host 192.168.1.100 app youtube
177
+ gtv-remote send --host 192.168.1.100 key POWER
178
+ ```
179
+
180
+ ### Device Status
181
+
182
+ ```bash
183
+ gtv-remote status --host 192.168.1.100
184
+ ```
185
+
186
+ ## App Shortcuts
187
+
188
+ | Shortcut | App |
189
+ |----------|-----|
190
+ | `youtube` | YouTube |
191
+ | `netflix` | Netflix |
192
+ | `disney` | Disney+ |
193
+ | `prime` / `amazon` | Prime Video |
194
+ | `kodi` | Kodi |
195
+ | `plex` | Plex |
196
+ | `hbo` | HBO Max |
197
+ | `hulu` | Hulu |
198
+ | `spotify` | Spotify |
199
+ | `twitch` | Twitch |
200
+ | `appletv` | Apple TV |
201
+ | `crunchyroll` | Crunchyroll |
202
+ | `browser` | Web Browser |
203
+
204
+ You can also launch any app by its package name: `app com.example.myapp`
205
+
206
+ ## Troubleshooting
207
+
208
+ - **No devices found**: Make sure your TV is on and connected to the same Wi-Fi network
209
+ - **Authentication failed**: Run `pair` to re-pair with the device
210
+ - **Connection refused**: Ensure the Android TV Remote Service is installed (Settings > Apps > Show system apps)
211
+ - **Pairing code not appearing**: Restart the Android TV Remote Service or reboot the TV
212
+
213
+ ## How It Works
214
+
215
+ 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.
gtv_remote-0.1.0/gtv/__init__.py ADDED
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
gtv_remote-0.1.0/gtv/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from gtv.cli import main
2
+
3
+ main()