Claude
6db1db70a0
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
95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
# 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.
|