Universal Web & Terminal Remote for Android TV & Projectors

A high-performance, zero-install Web Remote and CLI Controller designed for HY300, HY320, Magcubic, and generic Android TV / Google TV / Fire TV devices.

If your physical projector remote is lost, broken, or unresponsive, this tool restores complete control over local Wi-Fi using standard Android Debug Bridge (ADB). No Android rooting, no custom APK sideloading, and no external cloud services are required.

---

Quick Start Guide

Enabling ADB on Your Projector / Android TV

Before connecting over the network, enable Developer Options and Network Debugging:

1. On your projector or TV, navigate to Settings > About Device.
2. Locate Build Number and click it 7 times until a prompt confirms "You are now a developer".
3. Return to Settings > Developer Options (or Preferences).
4. Enable USB Debugging.
5. Enable Network Debugging / Wireless Debugging (if present as a separate toggle).
6. Find your projector's local IP under Settings > Network & Internet > Connected Wi-Fi > Status Information.
7. If your device displays a prompt stating "Allow USB Debugging from this computer?", check "Always allow from this computer" and select OK.

---

Option A(recommended): Web Control Panel (Windows, Linux, macOS with Python)

Prequisite: Download and extract the Android Developer Bridge Download

https://dl.google.com/android/repository/platform-tools-latest-windows.zip

Into the extracted folder e.g

Downloads\platform-tools-latest-windows\platform-tools

1. Clone or download this repository:

   git clone https://github.com/ederaefe/universal-android-tv-remote.git

2. Place adb.exe (or adb on Linux/macOS) in the folder, or ensure adb is in the same folder.
3. Start the server:
   • Windows: Double-click remote.bat or run:

     python remote.py

   • Linux / macOS:

     python3 remote.py 

4. The web control panel opens automatically at http://127.0.0.1:7070.
5. (Optional) Install Scrcpy for 60 FPS Ultra-Low Latency Live Mirroring:

   python scripts/install_scrcpy.py

---

Option B: Terminal Remote (remote.sh for Linux, macOS & BSD)

For lightweight environments without Python:

1. Make the script executable:

   chmod +x remote.sh

2. Run with your device IP:

   ./remote.sh 192.168.100.5

3. Control navigation directly using keyboard keys:
   • Arrows / WASD: D-Pad navigation
   • Enter / Space: OK / Select
   • Esc / Backspace: Back
   • H: Home
   • M: Menu
   • O: Settings
   • + / -: Volume Up / Down
   • X: Mute
   • P: Power Toggle
   • T: Send text prompt
   • Q: Quit

---

---

Key Features

• 60 FPS Ultra-Low Latency Live Mirror (Scrcpy v4.1): Real-time hardware-accelerated H.264 screen mirroring with sub-50ms latency and full mouse/keyboard pass-through, launchable directly from the web studio.
• Hard Connection Power-Cycle Reset: Single-tap network reset on the studio Refresh button that drops stale ADB pipes, flushes OS socket tables, reconnects, and auto-discovers projector IP changes across local subnets.
• Standalone Single-File Web UI (index.html): Self-contained HTML5 interface with embedded CSS and JavaScript. Zero bundlers, zero npm dependencies, and zero build steps.
• Mobile & Desktop Optimized: Responsive virtual remote for smartphones and full command control panel for desktop workstations.
• Directional Navigation: D-Pad (Up, Down, Left, Right, OK, Back, Home, Menu, Settings) over persistent ADB shell pipes for sub-10ms response.
• Virtual Touchpad & Hardware Cursor: Smooth mouse motion, tap-to-click, wheel scrolling, and hardware cursor toggle for projector pointer modes.
• Core Launchers with Deep-Linking (⋮): Top-right kebab action menus on YouTube and Browser cards for 1-click video link casting, direct search, and URL opening.
• Ambient Floating Command Stream Overlay: Live, non-distracting pill stream of in-flight commands with an instant cancellation purge button.
• Audio & Power Controls: Volume up, volume down, mute toggle, and power/standby switches.
• Instant Keyboard Text Injection: Stream text strings directly into Android search bars and login inputs without on-screen keyboard typing fatigue.
• App Shortcuts: 1-click launchers for YouTube, Netflix, Prime Video, Browser, HDMI Source Switcher, Settings, and Cast/Miracast.
• Linux & macOS Terminal Remote (remote.sh): Interactive raw-terminal controller for environments without Python or web browsers.
• Subnet Auto-Discovery: Automatic network scan across local IPv4 subnets to detect active ADB devices on port 5555.
• Remote File Manager & Storage Inspector: Browse partitions, monitor disk usage, install APKs, and transfer files.

---

Device Compatibility

Device Category	Supported Models / Platforms	Connection Method
Smart Projectors	HY300, HY300 Pro, HY320, Magcubic, Salange, Allwinner H713	Wi-Fi (ADB Port 5555) / USB
Android TV / Google TV	Xiaomi Mi Box/Stick, Chromecast with Google TV, Mecool, Nvidia Shield	Wi-Fi (ADB Port 5555)
Amazon Fire TV	Fire TV Stick, Fire TV Cube, Fire TV Edition	Network ADB (Port 5555)
Generic Android Boxes	Rockchip (RK3328/RK3566), Amlogic (S905X), Allwinner	Wi-Fi / Ethernet / USB

---

Prerequisites: Android SDK Platform-Tools

To keep this repository clean and avoid shipping untrusted binary blobs, Google's official adb binary is not bundled in git. Download the official platform-tools package for your operating system:

Official Google CDN Download Links

• Windows: Download Platform-Tools for Windows
• Linux: Download Platform-Tools for Linux
• macOS: Download Platform-Tools for macOS

Package Manager Installation (Recommended)

• Debian / Ubuntu / Raspberry Pi:

  sudo apt update && sudo apt install adb

• macOS (Homebrew):

  brew install android-platform-tools

• Windows (winget):

  winget install Google.PlatformTools

• Arch Linux:

  sudo pacman -S android-tools

---

Project Structure

├── index.html              # Standalone web remote (inline CSS/JS, 0 dependencies)
├── remote.py               # Lean Python HTTP server & ADB controller
├── remote.sh               # POSIX/Bash interactive terminal remote
├── remote.bat              # Windows environment validator and launcher
├── scripts/
│   ├── install_scrcpy.py   # Downloader and extractor for portable Scrcpy v4.1
│   └── bundle_release.py   # Production release archiver and packaging utility
├── bin/scrcpy/             # Local Genymobile Scrcpy v4.1 binaries (git-ignored)
├── .gitignore              # Ignores platform-tools binaries and temporary logs
├── LICENSE                 # MIT License
├── README.md               # User guide and SEO reference
└── documentation.md        # Technical architecture and API contract

---

REST API Reference

The local server exposes standard JSON endpoints:

• POST /cmd: Dispatch key action (e.g. {"key": "up"})
• POST /mouse: Dispatch touch/mouse coordinate event
• POST /mouse_rel: Dispatch cursor delta ({"dx": 10, "dy": 0})
• POST /text: Stream text input ({"text": "Search Title"})
• POST /app: Launch app package ({"app": "youtube"})
• POST /connect: Connect to target IP ({"ip": "192.168.1.100"})
• POST /launch_scrcpy: Launch native 60 FPS hardware mirror window
• POST /stop_scrcpy: Terminate active 60 FPS hardware mirror
• GET /scrcpy_status: Query mirror process status
• GET /status: Query connection status and active input nodes

---

License

This project is licensed under the MIT License. You are free to use, modify, distribute, and integrate it into your personal or commercial setups.