Metadata-Version: 2.1
Name: volatouch
Version: 1.3.0
Summary: Zero-dependency ultra-low latency bidirectional remote control for PC and Android phone over Wi-Fi.
Home-page: https://github.com/ugurturkerkebeci/volatouch
Author: Uğur Türker Kebeci
Author-email: Uğur Türker Kebeci <167927605+ugurturkerkebeci@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/ugurturkerkebeci/volatouch
Project-URL: Repository, https://github.com/ugurturkerkebeci/volatouch
Project-URL: Issues, https://github.com/ugurturkerkebeci/volatouch/issues
Keywords: remote-desktop,trackpad,air-control,mouse,keyboard,low-latency,zero-dependency,screen-stream,websockets,android,termux
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Multimedia :: Graphics :: Capture
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

<p align="center">
  <img src="https://raw.githubusercontent.com/ugurturkerkebeci/volatouch/main/assets/banner.jpg" alt="Volatouch Banner" width="100%" />
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/ugurturkerkebeci/volatouch/main/assets/logo.jpg" alt="Volatouch Logo" width="120" style="border-radius: 24px;" />
</p>

<h1 align="center">VOLATOUCH</h1>

<p align="center">
  <strong>Zero-Dependency Ultra-Low Latency Bidirectional Remote Control for PC & Android over Wi-Fi</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/volatouch/"><img src="https://img.shields.io/pypi/v/volatouch.svg?color=6366f1&style=for-the-badge" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/volatouch/"><img src="https://img.shields.io/pypi/pyversions/volatouch.svg?color=06b6d4&style=for-the-badge" alt="Python Versions" /></a>
  <a href="https://github.com/ugurturkerkebeci/volatouch/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-emerald.svg?style=for-the-badge" alt="License: MIT" /></a>
  <img src="https://img.shields.io/badge/Dependencies-0_Packages-22c55e.svg?style=for-the-badge" alt="0 Dependencies" />
  <img src="https://img.shields.io/badge/Footprint-<100_KB-8b5cf6.svg?style=for-the-badge" alt="Ultra-Lightweight" />
  <img src="https://img.shields.io/badge/Platform-Windows_%7C_Android_(Termux)-0284c7.svg?style=for-the-badge" alt="Platform: Windows | Android" />
</p>

<p align="center">
  <a href="#quick-start">⚡ Quick Start</a> •
  <a href="#bidirectional">🔄 Bidirectional Modes</a> •
  <a href="#zero-dependency">🌟 Zero Dependencies</a> •
  <a href="#features">✨ Features</a> •
  <a href="#gestures">📱 Controls Cheatsheet</a> •
  <a href="#cli-usage">💻 CLI Usage</a> •
  <a href="#security">🛡️ Security</a> •
  <a href="#from-source">🛠️ From Source</a>
</p>

---

<a id="quick-start"></a>
## ⚡ Quick Start

Volatouch is a pure Python application with **ZERO third-party pip dependencies**.

### Scenario A: Control your PC from your Phone 📱 ➔ 💻
1. On your Windows PC, install and run:
   ```bash
   pip install volatouch
   volatouch
   ```
2. Open the printed URL (e.g. `http://192.168.1.5:8000`) in Chrome or Safari on your phone.
3. Your phone instantly becomes a wireless multi-touch trackpad, air mouse, and keyboard for your PC.

### Scenario B: Control your Android Phone from your PC (Plug & Play, Zero-Root) 💻 ➔ 📱
No Termux or root setup required on your phone!

1. Connect your Android phone to your PC via USB cable (or Wi-Fi).
2. Enable **USB Debugging** in Developer Options and tap **[Allow]** on your phone screen.
3. On your PC, simply run:
   ```bash
   pip install volatouch
   volatouch --phone
   ```
   *(Volatouch automatically configures standalone Google ADB tools on demand—zero manual SDK setup required!)*
4. Open `http://localhost:8000` in your PC browser to view and control your phone with your mouse, trackpad, and keyboard!

> 💡 **Advanced (Phone-Hosted):** If you prefer running the server directly on your phone, launch Termux with Shizuku (`rish -c volatouch`) or Wireless Debugging (`adb connect localhost:<port> && volatouch`).

---

<a id="bidirectional"></a>
## 🔄 Smart Bidirectional Engine

Volatouch automatically detects the host environment and adapts its streaming and input pipelines:

| Mode | Host Device | Client Device | Capabilities |
| :--- | :--- | :--- | :--- |
| **PC Host** | Windows PC | Smartphone Browser | 60 FPS Win32 GDI+ desktop stream, Direct & Trackpad touch gestures, full virtual QWERTY keyboard, drag lock, mouse wheel. |
| **Android Host** | Android (Termux) | PC Desktop Browser | Native `/system/bin/screencap` stream, mouse click/drag touch emulation, mouse wheel swipe scrolling, physical PC keyboard sync, Android hardware navigation bar (`Back`, `Home`, `Recents`, `Power`, `Volume`). |

*You can also manually enforce a specific mode via CLI: `volatouch --mode pc` or `volatouch --mode phone`.*

---

<a id="zero-dependency"></a>
## 🌟 100% Zero-Dependency Architecture

Unlike heavy remote desktop applications requiring OpenCV, NumPy, FastAPI, Uvicorn, or pynput, Volatouch uses **only Python's standard library**:

- **0 External Packages on PyPI:** Pure Python standard library (`asyncio`, `subprocess`, `struct`, `ctypes`, `socket`, `time`, `os`).
- **Native Hardware Capture:**
  - **Windows:** Hardware-level screen capture (<2ms) and native JPEG compression via Win32 `ctypes` (`GDI32` and `GDIPlus`).
  - **Android:** Direct framebuffer capture via `/system/bin/screencap -p` with zero external image processing tools.
- **Built-in Asyncio HTTP & WebSocket Server:** RFC-6455 compliant WebSocket server and static file server running on standard library `asyncio`.
- **Hardware Input Emulation:**
  - **Windows:** Native `SendInput` / `user32` calls for pixel-accurate mouse and Unicode keyboard events.
  - **Android:** Native `/system/bin/input` injection for taps, swipes, text typing, and key events.
- **Pre-Bundled Web Client:** Complete React + Tailwind interface pre-compiled and bundled inside the package (~230 KB), requiring zero Node.js runtime.

---

<a id="features"></a>
## ✨ Key Features

- **🚀 High-Speed Hardware Streaming:** Low-latency video pipeline with 8-byte double timestamp headers for precise latency measurement.
- **🎯 Dual Touch Navigation Modes:**
  - **Direct Target Mode:** Tap anywhere to immediately position the cursor or touch event at that screen location.
  - **Relative Trackpad Mode:** Multi-touch trackpad navigation with smooth acceleration curves.
- **🏝️ Draggable Floating Action Island:**
  - Dedicated **L-Click** and **R-Click** action triggers.
  - **HOLD / LOCKED Button:** Persistent mouse-down lock with vibration feedback for seamless drag-and-drop operations.
  - **UP & DOWN Scroll Buttons:** Quick micro-step mouse wheel scrolling.
  - **Boundary Clamping:** Widgets automatically stay within viewports during rotation or fullscreen toggle.
- **🤖 Dedicated Android Navigation Bar:**
  - Floating pill when controlling Android: ◀ Back, ⌂ Home, ▢ Recents, ⚡ Power, 🔊 Volume Up, 🔉 Volume Down.
  - Right-clicking on the phone canvas automatically triggers the Android **Back** action.
- **⌨️ Dual Keyboard Options:**
  - Full **QWERTY On-Screen Keyboard** with Caps/Shift switching and sticky modifiers (`Ctrl`, `Alt`, `Shift`, `Win`).
  - **Physical Desktop Keyboard Sync:** Type directly on your physical computer keyboard to inject text into your Android phone.
- **📱 Responsive Display Modes:** Instant toggle between **Fit** (aspect ratio preservation) and **Fill** (zero black bars edge-to-edge).
- **🌐 Bilingual Support:** Instant toggle between English and Turkish.

---

<a id="gestures"></a>
## 📱 Controls & Gestures Cheatsheet

| Input Action | When Controlling PC (from Phone) | When Controlling Phone (from PC) |
| :--- | :--- | :--- |
| **Left Click / 1-Finger Tap** | Left mouse click | Touch tap at screen coordinates |
| **Right Click / 2-Finger Tap** | Right mouse click | Android **Back** navigation action |
| **Mouse Drag / 1-Finger Drag** | Move cursor or drag | Swipe / drag across screen |
| **Mouse Wheel / 2-Finger Scroll**| Scroll desktop page | Swipe scroll up / down |
| **Physical Keyboard Typing** | Type on virtual keyboard | Type directly into active phone input |
| **Navigation Pill** | N/A | Quick Back, Home, Recents, Power, Vol |

---

<a id="cli-usage"></a>
## 💻 CLI Usage

```text
usage: volatouch [-h] [--host HOST] [--port PORT] [--quality QUALITY]
                 [--scale SCALE] [--mode {auto,pc,phone}] [--version]

Volatouch: Ultra-Low Latency Mobile Air Control & Wireless Trackpad for PC over Wi-Fi (Zero Dependencies).

optional arguments:
  -h, --help            Show this help message and exit
  --host HOST           Host network interface to bind (default: 0.0.0.0)
  -p PORT, --port PORT  Port to listen on (default: 8000)
  -q QUALITY, --quality QUALITY
                        Initial stream quality (10-100, default: 55)
  -s SCALE, --scale SCALE
                        Initial resolution scale (0.2-1.0, default: 0.70)
  -m MODE, --mode {auto,pc,phone}
                        Execution mode: 'auto' (detect platform), 'pc' (control PC from phone), or 'phone' (control Android from PC)
  -v, --version         Show program's version number and exit
```

### Examples:

```bash
# Automatic environment detection (default)
volatouch

# Force phone host mode (when testing or running in Android terminal)
volatouch --mode phone

# Custom network port and high quality
volatouch -p 8080 -q 75 -s 0.85
```

---

<a id="security"></a>
## 🛡️ Security & Sandbox

1. **Subnet Verification (RFC-1918):** Only devices connected to the same private `/24` Wi-Fi subnet can access endpoints or establish WebSocket handshakes. External networks receive an immediate `403 Forbidden`.
2. **Strict Origin & CSP Protection:** Enforces modern `Content-Security-Policy`, `X-Frame-Options: DENY`, and strict frame-ancestor protections.
3. **Whitelisted Hardware Commands:** Only explicit, sanitized commands (`mouse_move`, `mouse_click`, `key_tap`, `android_nav`, etc.) are processed. Arbitrary command execution is impossible.
4. **Failsafe Release:** Whenever a connection drops, all pressed keys and buttons are instantly cleared to prevent stuck keys.

---

<a id="from-source"></a>
## 🛠️ Running From Source

```bash
# 1. Clone repository
git clone https://github.com/ugurturkerkebeci/volatouch.git
cd volatouch

# 2. Run immediately (0 dependencies needed!)
python run.py
```

---

## 📄 License

Distributed under the **MIT License**. See [`LICENSE`](./LICENSE) for full details.

---

<p align="center">
  Crafted with ❤️ by <a href="https://github.com/ugurturkerkebeci">Uğur Türker Kebeci</a>
</p>
