Add local ADB web remote for Android TV
Node/Express server shells out to adb (connect/pair/keyevent/text/app launch) and serves a mobile-first installable PWA remote: power, mute, input switch, volume/channel rockers, D-pad, media transport, text entry, and one-tap streaming app launch. Supports multiple saved TVs and the Android 11+ wireless-debugging pairing flow. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RSVyYcrjrbmrMKT85G4fyn
This commit is contained in:
Claude
@@ -0,0 +1,94 @@
|
||||
# TV ADB Remote
|
||||
|
||||
A slick, installable web remote for Android TV, controlled over ADB. Run a
|
||||
small Node server on any always-on machine on your home network (a Pi, NAS,
|
||||
old laptop, home server); point your phone's browser at it and control the
|
||||
TV from a mobile-optimized PWA.
|
||||
|
||||
Why a local web app instead of a native Android app: Android TV only
|
||||
exposes control over ADB once you enable network debugging, and the
|
||||
official ADB tooling is a desktop program. Rather than reimplement the ADB
|
||||
protocol inside a phone app, this runs `adb` on a machine that already has
|
||||
it, and serves a touch-friendly remote UI to any phone/tablet browser on the
|
||||
LAN. Add to the home screen and it behaves like an installed app.
|
||||
|
||||
## Features
|
||||
|
||||
- Power, mute, input switch, volume rocker, channel rocker
|
||||
- D-pad navigation, OK, back, home, menu
|
||||
- Media transport (rewind / play-pause / fast-forward)
|
||||
- Text entry (e.g. search boxes) sent as real keystrokes
|
||||
- One-tap launch for common streaming apps (Netflix, YouTube, Prime Video,
|
||||
Disney+, Spotify, Plex)
|
||||
- Manage multiple TVs, each remembered with a friendly name
|
||||
- Built-in pairing flow for Android 11+ ("Wireless debugging")
|
||||
- Installable PWA with offline app shell
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js 18+ and `adb` (Android platform-tools) installed **on the machine
|
||||
running the server** — not on the phone.
|
||||
- macOS: `brew install android-platform-tools`
|
||||
- Debian/Ubuntu: `sudo apt install android-tools-adb` (or
|
||||
`android-sdk-platform-tools`)
|
||||
- Windows: download "SDK Platform-Tools" from developer.android.com and
|
||||
put `adb.exe` on PATH
|
||||
- The TV and this server on the same local network.
|
||||
|
||||
## Set up the TV
|
||||
|
||||
1. On the Android TV: Settings → System (or Device Preferences) → About →
|
||||
tap "Build" repeatedly to enable Developer options.
|
||||
2. Settings → Developer options → turn on **Network debugging** (older
|
||||
Android TV) or **Settings → System → Developer options → Wireless
|
||||
debugging** (Android 11+ / Google TV).
|
||||
3. Note the IP address shown (Settings → Network & Internet).
|
||||
- Android TV ≤ 10: that's it — the debug port (5555) is open.
|
||||
- Android 11+ / Google TV: it shows a separate pairing IP:port and a
|
||||
6-digit code. Use the app's "Pair a new Android 11+ TV" flow, then add
|
||||
the TV using its regular IP (still port 5555 once paired).
|
||||
|
||||
## Run the server
|
||||
|
||||
```sh
|
||||
cd server
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
This serves the app at `http://<this-machine's-LAN-IP>:8787`. Open that URL
|
||||
on your phone, add your TV by IP in Settings (⚙), then optionally "Add to
|
||||
Home Screen" for a full-screen, app-like remote.
|
||||
|
||||
Override the port with `PORT=9000 npm start`, or point at a non-default
|
||||
`adb` binary with `ADB_BIN=/path/to/adb npm start`.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
cd server
|
||||
npm test
|
||||
```
|
||||
|
||||
Runs the server's unit tests (command construction, input validation,
|
||||
device persistence) using Node's built-in test runner — no real TV
|
||||
required.
|
||||
|
||||
## Project layout
|
||||
|
||||
```
|
||||
server/ Express app + ADB bridge (source of truth for control logic)
|
||||
src/adb.js Thin wrapper around the `adb` CLI (connect/pair/keyevent/…)
|
||||
src/keycodes.js Android KeyEvent constants used by the remote buttons
|
||||
src/deviceStore.js Persists saved TVs to data/devices.json
|
||||
src/index.js HTTP API + static file serving
|
||||
test/ Node test runner specs
|
||||
public/ The PWA served to phones (HTML/CSS/vanilla JS, no build step)
|
||||
scripts/ One-off dev scripts (icon generation)
|
||||
```
|
||||
|
||||
## Security note
|
||||
|
||||
This server has no authentication and will happily run `adb` commands
|
||||
against whatever IP you give it — it's designed to sit on your trusted home
|
||||
LAN, not the public internet. Don't port-forward it.
|
||||
Reference in New Issue
Block a user