# 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.