Skip to content
maxhayimPublic

About

A remote for Android TV in your phone's or computer's browser: D-pad, volume, apps and keyboard, paired with a PIN, nothing to install on the phone. Home network only.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Webmote Logo

A remote for your Android TV or car head unit, in your phone's or computer's browser

Android 9+ License Remote: iPhone, Android, desktop No app to install on the phone Home Assistant: add with HACS

Webmote

Webmote is an open-source remote for Android TV and Google TV that works in a web browser. Install it on the TV, open the address it shows on any phone, tablet or computer on the same Wi-Fi, type the PIN from the TV screen, and you have a remote like Google TV's: D-pad, OK, Back, Home, volume, play/pause, an Apps sheet and a keyboard for typing searches.

There is nothing to install on the phone and no account to sign in to, and nothing leaves your home network. Add the page to your phone's home screen and it opens full screen, like an app.

It also runs on Android car head units and tablets, where passengers get big track controls, volume, Back, Home, recent apps, the apps and a keyboard, over the car's hotspot. See In the car.

And it works with Home Assistant: each TV shows up there by itself, and once paired with its PIN it's a media player and a remote for dashboards, automations and voice. See Home Assistant.

Screenshots

The Webmote remote page on a phone    Webmote on the TV, showing the address and PIN (blurred here)

Left: the remote page (demo TV and apps). Right: Webmote on the TV, with the address and PIN blurred.

The Webmote remote page in a wide desktop browser window, D-pad on the left and buttons on the right

On a computer or a tablet on its side, the remote spreads out to fit the window (demo TV).

Features

  • Google-TV-style remote: D-pad with OK, Back, Home, volume up/down, mute, play/pause, and TV settings
  • Car head units and tablets: a touch layout with previous, play/pause and next in place of the D-pad, recent apps, and the device's own app drawer; works over a hotspot with no internet
  • Home Assistant: an integration (install with HACS) that finds the TVs on the network, pairs with the PIN, and adds each as a media player (on/off, volume, mute, play/pause, tracks, apps as sources), a remote (every button, typing and searching), a button for each remote key, and Webmote's updates
  • Bluetooth, as a second way in: with no shared Wi-Fi or hotspot (in a car, or a TV on another network), open the page on GitHub Pages in Chrome and connect over Bluetooth. Same remote, same PIN. See Over Bluetooth
  • QR code: Webmote's screen shows one for its address, so a phone opens the remote by pointing its camera at it
  • Turn off and on: hold the power button for a second to turn the TV off, so a stray tap doesn't; tap it to turn the TV back on (Standby keeps Webmote on the network while the TV is off)
  • Updates itself from this repository's releases, once a day. On Webmote's screen, Updates is Automatic, Notify only (checks, and Home Assistant shows the update, but installs only when you ask) or Off (never checks by itself). Silent on Android 12 and newer when installed with install.sh; elsewhere the TV asks once, only when you open Webmote's screen or ask for the update
  • Apps sheet: every app on the TV with its banner; tap one to open it
  • Keyboard: type on your phone and the text appears in the TV's focused search or text box, then Enter to search
  • Now playing: the TV's name, the app in front, and the volume, kept up to date
  • Hold to repeat on the D-pad and volume, with a small vibration on phones that have it
  • Desktop keyboard shortcuts: arrows, Enter, Backspace or Esc, H, + and −, M, Space, N and P for next and previous track, K for the keyboard, A for apps
  • Home-screen app: a web app manifest and icons, so it opens full screen from the home screen
  • Paired, not open: a 6-digit PIN pairs each browser; wrong guesses lock pairing for longer each time; New PIN signs every device out. See Security
  • Small: one ~45 KB APK, plain Java, no libraries, no tracking
  • A module card for the Clean Your TV launcher ("Webmote · Phone remote"); on any other home it's an ordinary app

Requirements

  • An Android TV or Google TV device, or an Android car head unit or tablet, on Android 9 or newer (on Android 13 and newer the D-pad works everywhere; see Known Limitations for 9 to 12)
  • A phone, tablet or computer with a modern browser, on the same network as the TV (in a car: the same hotspot); or, over Bluetooth, Chrome on Android or a computer, or the Bluefy browser on iPhone
  • To install: a computer with ADB and Developer options → Network debugging on the TV, or any sideloading app on the TV

Installation and Setup

From a release (recommended)

  1. Download Webmote-x.y.z.apk from the latest release.
  2. Install it and switch on its remote service:
    TV_HOST=<tv ip> APK=Webmote-0.5.0.apk ./install.sh
    
    This installs the APK with adb, adds Webmote's remote service to the accessibility services already on (keeping theirs), and opens Webmote on the TV.

Installing without a computer: sideload the APK with any file manager or downloader app, open Webmote, choose Remote service and switch on Webmote in Accessibility settings. Some TVs hide that screen; then use install.sh once from a computer.

From source

JDK 17 and Android SDK platform 34 with build-tools 34.0.0:

TV_HOST=<tv ip> ./install.sh

It builds the app and installs it the same way. To build only: ./gradlew assembleRelease; the JVM tests run with ./gradlew testReleaseUnitTest, and the Home Assistant integration's with pip install -r tests/requirements.txt then pytest tests (Python 3.12 or newer). Where macOS blocks the stock adb, set CLEANYOURTV to a clone of Clean Your TV with its tools set up, and its tools/tv.py is used instead.

Usage

  1. Open Webmote on the TV. It shows an address like http://192.168.1.20:8080, a QR code of it, and a 6-digit PIN.
  2. Point your phone's camera at the QR code, or open the address in the browser on your phone or computer, and type the PIN. The TV also shows the PIN in a corner while the browser is on the pairing page, so after the first time you can skip opening Webmote on the TV. The browser stays paired.
  3. Add it to your home screen:
    • iPhone and iPad (Safari): Share → Add to Home Screen. It opens full screen, like an app.
    • Android (Chrome): ⋮ → Add to Home screen. Over plain HTTP, Chrome adds a shortcut that opens in a browser tab; tap the full-screen button at the top of the remote to hide the browser bars.
    • Computer: bookmark it, and use the keyboard shortcuts listed under the remote.

The address is the TV's address on your network. If your router hands it a new one, Webmote shows the new address; give the TV a fixed address (a DHCP reservation in the router) to keep the home-screen icon working. If port 8080 is taken, Webmote uses the next free port, up to 8089.

On the TV, New PIN (press OK twice) makes a new PIN and signs out every paired phone and computer.

For scripts and home automation, the same calls the page makes are documented in docs/api.md.

In the car

Aftermarket Android head units (the Android tablets built into a car stereo) run Webmote like a TV, with a layout for touch: previous, play/pause and next, volume, Back, Home, recent apps, the head unit's apps and a keyboard. There's no home Wi-Fi in a car, so join the phone and the head unit through a hotspot, either way round:

  • The head unit on the phone's hotspot (the usual way, for the head unit's internet): open Webmote on the head unit and scan its QR code with the phone.
  • The phone on the head unit's hotspot, where the head unit has one: the same, with no mobile data needed. Its address is often http://192.168.43.1:8080.

Webmote shows the hotspot's address even when the head unit's mobile data is its active network. A hotspot's address can change between drives, so scan the code again if the saved page can't reach the head unit. It's for passengers: the driver keeps their eyes on the road.

No hotspot? Use Bluetooth instead.

To trim a head unit's preinstalled apps first, or try another launcher on it, see CleanYourHeadUnit.

Cars with Android built in from the factory (Android Automotive, such as Polestar, Volvo and some GM models) don't allow apps like this, so Webmote can't run there.

Over Bluetooth

A second way in, for a TV or car screen your phone can't reach over Wi-Fi. Webmote's own page is plain HTTP, where browsers don't allow Bluetooth, so this uses the same page from GitHub Pages:

  1. On the TV or head unit, open Webmote and switch on Bluetooth remote (allow it if asked). It stays off until you do.
  2. On the phone, open maxhayim.github.io/webmote in Chrome (Android or a computer) or the free Bluefy browser (iPhone and iPad: Safari has no Web Bluetooth), and tap Connect.
  3. Pick the TV or head unit from the list, then type the PIN it shows. That browser stays paired with it; next time, tap Connect and pick it again.

Everything works as over Wi-Fi except the apps' pictures, which are left out to keep it quick. It reaches about as far as a Bluetooth speaker. Many aftermarket head units keep their Bluetooth for calls and music, where apps can't use it: then Webmote's screen says Can't next to Bluetooth remote, and the hotspot is the way in.

Home Assistant

Webmote comes with a Home Assistant integration, in custom_components/webmote. Each TV running Webmote 0.4.0 or newer announces itself on the network, so Home Assistant finds it the way it finds a Chromecast, and pairing takes the same PIN as a phone.

Open your Home Assistant and add Webmote in HACS   Open your Home Assistant and add a Webmote TV

Left: opens Webmote in HACS in your own Home Assistant. Right: once it's downloaded, adds a TV by its address (TVs on the network are offered under Discovered by themselves).

  1. Press the first button above and confirm, or in HACS: ⋮ → Custom repositories, add https://github.com/maxhayim/webmote as an Integration, then download Webmote and restart Home Assistant. Restart even if HACS doesn't ask: Home Assistant only starts looking for Webmote TVs on the network when it starts up. HACS adds a custom repository only once it's connected to GitHub; without that, install it as below.
  2. With the TV on, open Settings → Devices & services. The TV is listed under Discovered; choose Add. (Not listed, for instance on another subnet: Add integration → Webmote and type the address from Webmote's screen.)
  3. The TV shows a PIN in a corner of its screen. Type it in Home Assistant.

Without HACS (or with HACS not connected to GitHub), install it from the latest release, then restart Home Assistant and carry on from step 2:

  • With the Terminal & SSH add-on, paste this one line (run it again to update):
    mkdir -p /config/custom_components && curl -fsSL https://github.com/maxhayim/webmote/releases/latest/download/webmote-home-assistant.tar.gz | tar -xz -C /config/custom_components
    
  • By hand: download webmote-home-assistant.zip from the release, unzip it, and put the webmote folder in Home Assistant's config/custom_components folder (with the Samba share or the File editor add-on).

Installed this way, Home Assistant doesn't tell you about updates: watch this repository's releases, and run the line again (or copy the new folder) when there's a new one.

Each TV becomes a device with:

  • Media player: on while the screen is on, off while the TV sleeps; volume (set, up and down), mute, play/pause, next and previous track, turn on and off, and the TV's apps as sources (choose one to open it). It works with Home Assistant's media cards, voice ("turn the living room TV volume down") and automations.
  • Remote: remote.send_command with any button by its API name (up, down, left, right, ok, back, home, recents, settings, vol_up, vol_down, mute, play_pause, next, previous, on, off, power); text:words types into the TV's focused text box and search:words also presses Enter (in YouTube, it searches). The apps are its activities: remote.turn_on with an activity opens that app.
  • Buttons: Up, Down, Left, Right, OK, Back, Home, Recent apps and Settings, one entity each, for the device page and dashboards (a car head unit or tablet gets no D-pad).
  • Webmote app: an update entity with the TV's Webmote version and the latest release; Install has the TV update itself.
action: remote.send_command
target:
  entity_id: remote.living_room_tv
data:
  command: [home, down, ok]

If the TV's address changes, Home Assistant follows it. If someone presses New PIN on the TV, Home Assistant asks to pair again.

Turning the TV on works from Webmote 0.5.0's Standby (on by default on TVs, off on car head units and tablets so a parked car's battery isn't run down; on Webmote's screen): while the screen is off, Webmote keeps the TV on the network, so Home Assistant and the page's power button can turn it back on. That costs a little power while the TV is off. Android's battery saving (Doze) puts apps to sleep anyway unless they're let off it; install.sh does that for Webmote. A TV that falls asleep off the network can only be woken by its own remote, HDMI-CEC, or its own Google Home support.

How It Works

   Phone / computer                         Android TV
  ┌────────────────┐   home Wi-Fi    ┌──────────────────────────┐
  │    Browser     │  HTTP + key     │  Webmote                 │
  │  remote page   ├────────────────►│  ├─ tiny HTTP server     │
  │ (home screen)  │◄────────────────┤  ├─ pairing (PIN → key)  │
  └────────────────┘   status, apps  │  └─ accessibility service│
                                     │      presses the keys    │
                                     └──────────────────────────┘

Webmote runs a small HTTP server inside its accessibility service, so it serves the page while the service is on and stops when it's off. The page is a single HTML file inside the app.

  • D-pad, OK, Back, Home and Turn off are Android's own global actions for accessibility services, the same ones a switch-access device uses. No ADB, no root, and no input injection.
  • Volume and mute go through the audio service, and the TV shows its own volume bar. Play/pause is a media key, delivered to whichever app is playing.
  • Typing finds the text box that has focus on the TV and sets its text, like the Google TV app's keyboard does. YouTube (kids profiles included) draws its own keyboard with no text box behind it, so there Enter opens YouTube's search for what you typed. Netflix also draws its own keyboard but takes no search from outside, so it can't be typed into: use the D-pad on its keyboard.
  • Apps are the ones with a TV launcher entry (on a head unit or tablet, the app drawer's), opened the way the home screen opens them.
  • On the network, Webmote announces itself as _webmote._tcp (mDNS, like a printer or a Chromecast) with the TV's name and a random id, never a key, so Home Assistant can find it.
  • Standby: while the screen is off, Webmote holds a wake lock and a Wi-Fi lock so the TV stays on the network, and turns the screen back on with Android's own wake-up when asked. On TVs with HDMI-CEC, waking the device usually wakes the TV it's plugged into too.
  • Updates come from this repository's latest release: Webmote downloads its APK and checks it's Webmote, newer, and signed with the same key before handing it to Android's installer. GitHub is the only other place it contacts.
  • TV or touch: a device that isn't a TV (no Android TV feature, not in TV mode) gets the touch layout, with track controls in place of the D-pad.

Security

Anything that can press a TV's keys can open apps and change settings, so Webmote is locked down by default:

  • Only devices on your home network (private addresses, and VPN ranges like Tailscale's) can connect at all. Bluetooth, when switched on, reaches only as far as Bluetooth does, and asks for the same paired key.
  • Every control call needs a key that the TV gives out only for the PIN on its screen. After 5 wrong PINs, pairing locks for 30 seconds, doubling up to 5 minutes. A browser on the pairing page can ask the TV to show the PIN in a corner of its screen for a minute; that shows it to the room, not to the browser.
  • The TV stores only hashes of the keys. Pages on other websites can't use your paired browser to control the TV (no CORS, DNS-rebinding protection).
  • No accounts, no cloud, no analytics: nothing about you or your TV leaves your network. The only call out is the daily look at GitHub for a newer Webmote, which you can switch off (Updates: Off).

Never forward port 8080 to the internet. Webmote speaks plain HTTP on the home network, the usual trade-off for a local device. To use it away from home, use a VPN to your home network. Details, and how to report a vulnerability: SECURITY.md.

Known Limitations

  • Turning the TV on needs Standby. A TV asleep without it is off the network, so nothing on Wi-Fi can reach Webmote; use the TV's remote, HDMI-CEC from another device, or a voice assistant then.
  • Bluetooth needs Chrome or Bluefy (Web Bluetooth): not Safari or Firefox. Chrome asks you to pick the device each time the page opens.
  • The D-pad on Android 9 to 12 works in most apps, not all. The D-pad actions for accessibility services arrived in Android 13. Before that, Webmote moves the TV's focus itself and OK clicks what has it. That follows apps built from standard Android views (home screens, settings, most app menus), but not apps that draw their own screen, such as some games and video players.
  • Enter on Android 9 and 10 clicks the app's search button. Those versions have no Enter action for accessibility services, so Webmote clicks the search, send or go button the app shows instead; an app without one won't search on Enter. Some Android 9 and 10 TVs also route volume through their own service; Webmote tries each way of changing it until the level moves.
  • Android 8 and older aren't supported.
  • Android Chrome won't install it as a full app over HTTP. Browsers only install web apps from HTTPS, which a TV on a private address can't get. iPhone home-screen web apps open full screen anyway; on Android use the full-screen button.
  • Some apps ignore the keyboard. Apps that draw their own on-screen keyboard instead of a real text box can't receive typed text; use the D-pad there. YouTube is the exception: type, then press Enter to search it. Netflix is not.
  • The remote service has to stay on. Some TVs turn accessibility services off after an update or when memory is short; open Webmote on the TV to see whether it's on.

Tested On

MOKA R8G (Android 14). Verified from a computer on the same network: pairing with the PIN and refusing a wrong one; calls without a key refused; a request with a host name instead of the TV's address refused; Home, Back, left and right, and TV settings; the Apps list (73 apps), app banners and opening an app, with an app outside the TV launcher list refused; the TV's name and the app in front; "no text box has focus" when there was none; the pairing surviving an app update. The remote page was checked in desktop Chrome against a stand-in for the TV.

ASUS M1G (Android 11): installed and in use; its owner confirmed the remote works.

Wanbo T6 Max projector (Android 9, firmware 20220419), by @dicklamman (#2): pairing, the Apps list and opening apps, Home, Back, Recents, the D-pad, OK, volume, mute and play/pause.

Not tested yet: a car head unit or tablet (the touch layout, the app drawer list and the hotspot address); volume, mute and play/pause (the test TV stayed muted), Turn off, typing into a real text box, and the page on an iPhone or Android phone, including the home-screen app. Reports welcome: open an issue.

License

This project is licensed under the MIT License.

See the LICENSE file for details. Full license text: https://opensource.org/licenses/MIT

Contributing

Pull requests are welcome. Open an issue first to discuss ideas or report bugs. See CONTRIBUTING.md and the Code of Conduct.

Related Projects

  • Clean Your TV: debloat tools and a lean launcher for Android TV, whose module cards Webmote supports
  • CleanYourHeadUnit: reversible, non-root debloat, privacy shield and launchers for aftermarket Android car head units, the devices Webmote's touch layout is for
  • Corner Player: your own camera or stream in a corner of the TV, over any app
  • ShackScreen: an Android TV dashboard for radio operators

Acknowledgments

The remote's layout follows the familiar Google TV remote; the icons and art are Webmote's own. Car head unit support was shaped alongside CleanYourHeadUnit.
Android™, Android TV™ and Google TV™ are trademarks of Google LLC, and iPhone® and Safari® are trademarks of Apple Inc.; they are used here solely to describe compatibility. Webmote is not affiliated with or endorsed by Google or Apple. All other trademarks are the property of their respective owners.

About

A remote for Android TV in your phone's or computer's browser: D-pad, volume, apps and keyboard, paired with a PIN, nothing to install on the phone. Home network only.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages