tv-adb-remote/README.md

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

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

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.