📱 Laptop Remote (Remote Deck)

Turn your smartphone into a powerful, low-latency remote control for your laptop. Control media playback, stream a high-precision trackpad, navigate with a virtual D-Pad and keyboard, and present with a real-time screen laser pointer.

⚠️ LAN-only tool. Designed for trusted local networks (home Wi-Fi / hotspot). Do not expose it to the public internet — see SECURITY.md.

📸 Screenshots

Media Controls	Touch Trackpad	Virtual Mouse	Presentation Deck

👀 View Real-World & Desktop Companion Preview

Laptop Terminal Server	Phone Controlling Laptop

✨ Features at a Glance

• ⚡ Terminal / Headless Edition: A lightweight, no-GUI server that prints a QR code and pairing PIN directly in the terminal.
• 🌐 Zero-Config Discovery: Connect instantly via QR code scan, local IP, or mDNS (http://remotedeck.local:5000).
• 🔒 Secure PIN Pairing: Protected with 6-digit rolling PIN verification, session Bearer tokens, and brute-force IP rate limiting.
• 🎵 Smart Media Deck: Context-aware media controls for YouTube, Netflix, Disney+ Hotstar, Prime Video, VLC, and web players.
• 🔍 Auto-Profile Detection: Automatically detects the active foreground window and switches key mappings on the fly.
• 🖱️ Low-Latency Trackpad: Smooth mouse movement powered by WebSockets, native OS input simulation, DPI scaling, tap-to-click, and 2-finger inertia scrolling.
• ⌨️ Keyboard & Navigation Keypad: Send text input/search queries directly to your laptop, use a 5-way D-Pad, and trigger 1-touch hotkey tiles (skip intro, cycle audio tracks, speed +/-).
• 📊 Presentation Mode with Laser Pointer: Projects a red laser dot across your laptop screen in real time, with slide controls, blackout mode, and an elapsed presentation timer.
• 📱 Progressive Web App (PWA): Installable to your phone's home screen for a distraction-free, full-screen remote experience.
• 🔋 Host Status: Live laptop battery percentage and active profile indicators.

🚀 Quick Start

1. Fastest Way: Zero-Install with uv (Recommended)

If you have uv installed (Windows, macOS, Linux):

# Run immediately in 1 second (no installation, zero PATH issues):
uvx laptop-remote

# Or install permanently as a global CLI tool:
uv tool install laptop-remote
laptop-remote

2. From Prebuilt Executable (Windows — No Python Needed)

1. Download LaptopRemote-CLI.exe from GitHub Releases.
2. Double-click LaptopRemote-CLI.exe (or run it in Command Prompt / PowerShell).
3. Connect your phone on the same Wi-Fi by scanning the printed QR code!

3. Via pip or pipx (Cross-Platform)

# Standard install (Windows, macOS, Linux):
pip install laptop-remote
laptop-remote

# If 'laptop-remote' is not recognized on Windows (Scripts folder not in PATH):
python -m laptop_remote
# or using Windows Python launcher:
py -m laptop_remote

# Modern Linux (Ubuntu/Debian) with pipx:
pipx install laptop-remote
laptop-remote

3. From Source (Developers / Git Clone)

git clone https://github.com/Sathyabalan6/laptop-remote.git
cd laptop-remote

# Install in editable mode
pip install -e .

# Run with an auto-generated PIN and ASCII QR code
laptop-remote

# Run with a custom PIN or different port
laptop-remote --pin 123456 --port 5000

# Enable HTTPS/WSS (self-signed cert auto-generated)
laptop-remote --ssl

Linux users can also use the launcher script:

./run.sh

🛠️ Remote Deck Controls & Tabs

🖱️ 1. Trackpad Tab (Precision Mouse & Drag Lock)

• High-Precision Trackpad: Move cursor with one finger. Backed by native OS cursor calls (win32api / macOS Quartz / Linux Wayland & X11) with DPI-scaled acceleration curves for smooth, responsive movement.
• Persistent Gesture Guide: Quick glanceable glyphs (👆 Move · 👇 Tap · ✌️ Scroll) for instant discoverability.
• Tap-to-Click: Tap trackpad surface for instant left-click.
• Tactile Click Buttons: Dedicated Left Click and Right Click pads.
• 🔒 Tactile Drag Lock: Dedicated toggle to keep the left mouse button held down for effortless window moving and text highlighting without finger gymnastics.
• 2-Finger Momentum Scroll: Drag with two fingers to scroll web pages, documents, or timelines with natural physics decay.
• 🎛️ Sensitivity Slider: Fine-tune cursor speed and acceleration response directly from your phone.

🎵 2. Media Remote Tab (Playback & Audio)

• Context-Aware Profiles: Auto-detects or lets you manually switch between YouTube / Hotstar, VLC Media Player, and Universal (Netflix / Prime / Web) with descriptive sub-labels.
• Tactile Playback Triad: Play / Pause toggle, Skip Backward 10s (⏪), and Skip Forward 10s (⏩).
• Direct Playback Rate Pills: Instantly select discrete playback speeds (0.75x · 1.0x · 1.25x · 1.5x · 2.0x).
• 🔊 Synchronized OS Audio: Continuous master volume slider with -5% / +5% tactile step buttons and instantaneous Mute toggle.
• Navigation & View: Subtitles (CC), Fullscreen toggle (⛶), Picture-in-Picture (Miniplayer), Theater mode, and Audio Track language cycling (VLC).

⌨️ 3. Dedicated Remote & Keys Tab (D-Pad, Typing & Macros)

• Live Typing & Search Dispatch: Type text or URLs on your phone and press Send to stream keystrokes directly to the active text field on your laptop.
• One-Touch Focus Pills:
  • / Find: Jumps directly to in-page search bars.
  • Ctrl+L URL Bar: Jumps focus to the browser's address bar.
• Tactile 5-Way D-Pad: High-contrast directional buttons (Up, Down, Left, Right, OK / Enter) with hold-to-repeat support for navigating menus, spreadsheets, and media lists.
• Browser Navigation Keys: Quick buttons for ◀ Back, Esc, Tab ⇥, ⌫ Delete, ⇧ Tab, Next Tab, and Reload.
• ⚡ System Productivity Macros:

  Macro Button	Hotkey Action	Supported OS
  Copy	Ctrl+C / Cmd+C	Windows, macOS, Linux
  Paste	Ctrl+V / Cmd+V	Windows, macOS, Linux
  App Switch	Alt+Tab / Cmd+Tab	Windows, macOS, Linux
  Screenshot	Win+Shift+S / Cmd+Shift+4	Windows, macOS, Linux
  Close Window	Alt+F4 / Cmd+W	Windows, macOS, Linux
  Lock PC	Win+L / Ctrl+Cmd+Q	Windows, macOS, Linux

📊 4. Presentation Deck & Laser Pointer Tab

• Screen Laser Pointer: Touch and drag your finger across the pad to project a smooth, hardware-rendered red laser dot over your laptop screen in real time.
• Asymmetric Slide Navigation: Giant Next Slide (70%) and Prev Slide (30%) buttons for confident, blind tactile control during speeches.
• Auto-Start Presentation: Mapped to F5 (or Ctrl+F5 when Google Slides, Canva, Prezi, or Docs are active).
• Blackout Screen: Blank the laptop display with one tap during presentations or breaks.
• Slide Counter & Live Timer: Track slide numbers and presentation duration automatically from first touch.
• ❓ Built-in Help Overlay: Tap (?) in the top header anytime to view visual gesture cheat sheets and preset documentation.

🔒 Security & Connection Details

• Rolling One-Time PIN: A fresh 6-digit PIN is generated upon startup and regenerated after each successful pairing or manual revocation.
• Brute-Force Protection: IP-based lockout triggers automatically after 5 consecutive incorrect PIN attempts (30-second escalating lockout).
• Bearer Token Authorization: Paired devices receive a cryptographically secure 48-character session token stored locally on your device.
• Dual Transport: High-frequency mouse coordinates and laser pointer positions stream over WebSockets for minimal latency, with automatic fallback to REST endpoints if required.
• Offline Self-Contained: Socket.IO client library and assets are fully bundled locally — no internet connection or CDN required.

⚙️ Configuration & Custom Presets

Key mappings are defined in presets.json. You can customize or add hotkeys for your favorite applications:

{
  "youtube_hotstar": {
    "play_pause": "space",
    "skip_forward": "l",
    "skip_back": "j",
    "skip_forward_30": ["l", "l", "l"],
    "next": ["shift", "n"],
    "fullscreen": "f",
    "subtitles": "c",
    "speed_up": ["shift", "."]
  },
  "universal": {
    "play_pause": "space",
    "skip_forward": "right",
    "skip_back": "left",
    "fullscreen": "f"
  }
}

💻 Developer Setup & Building Executables

Prerequisites

• Python 3.10+ installed and added to your system PATH.

Running from Source

# Install the package in editable mode (pulls in all dependencies)
pip install -e .

# Run the server (terminal edition)
python -m laptop_remote

Compiling a Standalone Executable (.exe)

• Windows: Double-click build.bat to build dist/LaptopRemote-CLI.exe.
• Linux: Run ./build.sh to build dist/LaptopRemote-CLI.

📁 Project Structure

laptop-remote/
├── pyproject.toml              # Packaging metadata & dependencies
├── requirements.txt            # Runtime dependencies
├── run.sh / build.sh           # Linux launcher / builder
├── build.bat / build_cli.bat   # Windows builders
├── setup_linux.sh              # One-time Wayland (ydotool) setup on Linux
├── presets.json                # Keyboard shortcut profiles (user-editable)
├── logo.ico                    # App icon
├── src/
│   └── laptop_remote/          # Main application package
│       ├── __init__.py
│       ├── __main__.py         # python -m laptop_remote
│       ├── server/             # Flask + SocketIO server package
│       │   ├── __init__.py     # public API (app, socketio, main)
│       │   ├── _app.py         # app construction & shared runtime state
│       │   ├── state.py        # build_state()
│       │   ├── routes_auth.py  # pairing, revoke, QR
│       │   ├── routes_input.py # mouse/key/text/pointer/volume
│       │   ├── websocket.py    # Socket.IO handlers
│       │   ├── discovery.py    # mDNS + preset monitor
│       │   └── main.py         # main() entry point
│       ├── cli.py              # Terminal/headless entry point
│       ├── core/               # Platform backends & utilities
│       │   ├── input.py        # Mouse/keyboard drivers (Windows/macOS/X11/Wayland)
│       │   ├── keys.py         # Key-name → Linux input-event keycode mapping
│       │   ├── auth.py         # PIN generation, bearer tokens, rate limiting
│       │   ├── config.py       # Presets JSON loader & path resolver
│       │   ├── network.py      # Local IP resolution & SSL certificate setup
│       │   ├── overlay.py    # Platform selection and Windows overlay
│       │   ├── overlay_x11.py # Linux X11 SHAPE overlay
│       │   ├── power.py        # Battery status monitor
│       │   ├── window.py       # Foreground window detection & auto-preset
│       │   ├── audio.py        # Cross-platform volume control
│       │   └── tray.py         # System tray icon manager
│       └── static/             # Web frontend (served as the remote UI)
│           ├── index.html
│           ├── css/            # tokens.css, base.css, components.css
│           └── js/             # app.js, transport.js, trackpad.js, ...
├── docs/                       # Design notes & research
├── tests/                      # pytest test suite
└── README.md

🖥️ Platform Support

Laser pointer note: Windows uses its native Tk overlay. Linux uses an X11 SHAPE 1.1 window with an empty input shape so mouse and touch events pass through. A direct Wayland session is not supported. XWayland availability depends on its display exposing SHAPE 1.1; if initialization fails, the app reports the pointer unavailable and keeps the laser pad hidden. macOS support is not yet implemented.

🧪 Running Tests

# Python backend tests (82 tests)
pip install -e ".[dev]"
pytest

# Frontend unit tests (17 Vitest tests)
npm install
npm test

Tests run automatically on Linux, Windows, and macOS via GitHub Actions.

🤝 Contributing

Contributions are very welcome! See CONTRIBUTING.md for setup instructions, coding guidelines, and platform testing notes. Please also read our Code of Conduct.

• 🐛 Report a bug
• ✨ Request a feature
• 💬 Ask a question

🔐 Security

This is a LAN-only tool. Please read SECURITY.md before reporting vulnerabilities or deploying it.

📄 License

This project is licensed under the MIT License — see LICENSE. Free to use, modify, and distribute for personal and commercial purposes.