Mouseless is a high-fidelity, low-latency virtual air mouse that allows you to control your computer completely in the air using hand gestures via a standard webcam. By combining advanced signal processing and direct OS integration, it delivers a precise, zero-jitter, and lag-free mouse control experience without requiring any physical hardware.
- 4-Knuckle Average Tracking: Coordinates are anchored to the average position of your four main knuckles (
INDEX_MCP,MIDDLE_MCP,RING_MCP,PINKY_MCP). Since knuckles remain stationary when your fingers curl, this physically eliminates click-drift. - One Euro Filter: Incorporates the industry-standard adaptive One Euro Filter to dynamically smooth cursor movements. It applies heavy filtering when your hand is still (eliminating tremors) and reduces filtering during fast movements (eliminating lag).
- Sub-Millisecond win32api Integration: Bypasses Python wrapper overhead (like PyAutoGUI) for mouse movement, clicking, and scrolling, executing direct C-level Windows user32 input events.
- Schmitt Trigger Click Hysteresis: Implements a double-threshold click system that prevents mouse click flickering or bouncing at gesture boundaries.
- Temporal Click/Drag Separation:
- Quick tap and release (<400ms) = Click.
- Press and hold (>=400ms) = Drag & Drop.
- Open-Palm Pause: Reposition your hand in the air comfortably by opening your palm (all 5 fingers extended) to temporarily freeze the cursor.
| Action | Hand Gesture | Description |
|---|---|---|
| Move Pointer | Hover Hand (knuckles tracked) | Moves the cursor smoothly across the screen. |
| Left Click | Thumb-to-Index-Knuckle Single Tap | Tap thumb tip to index knuckle and release quickly (<400ms). |
| Right Click | Thumb-to-Index-Knuckle Double Tap | Tap thumb tip to index knuckle twice quickly (within 250ms). |
| Drag & Drop | Thumb-to-Index-Knuckle Hold | Hold thumb tip to index knuckle for >=400ms and move hand. |
| Scroll Up/Down | Index + Middle Fingers Extended | Raise Index and Middle fingers together and move hand vertically. |
| Pause/Reposition | Open Palm | Extend all five fingers to freeze cursor and reposition hand. |
To help you get started, here are the core hand postures and how they are classified by the system:
| Pause (Open Hand) | Dragging (Fist Hold) | Scrolling (Two Fingers Up) | Tapping (Knuckle Tap) |
|---|---|---|---|
 |  |  |  |
The system tracks the 4-knuckle average (visualized above) to keep the cursor completely stable during taps and transitions.
- Windows OS (required for direct Win32 API low-latency mouse event execution).
- Python 3.12 installed.
git clone https://github.com/vaavgit/mouseless.git
cd mouselessInstall the required computer vision and automation packages:
pip install opencv-python mediapipe pyautoguiStart the air mouse stream:
py -3.12 main.pyTip: On startup, look at the webcam feed and keep your hand relaxed to initialize the stream. Press Q in the camera preview window at any time to quit cleanly.
All configurations, sensitivity scales, active region bounds, and gesture thresholds are managed in a single file: config.py. Tunable parameters include:
POINTER_SENSITIVITY: General pointer speed multiplier.POINTER_ACCELERATION_FACTOR: Non-linear velocity-scaling.ONE_EURO_MIN_CUTOFF&ONE_EURO_BETA: Jitter and lag damping.ACTIVE_ZONE: Crop region in the camera frame mapped to your full screen for comfortable reach.
This project is licensed under the MIT License - see the LICENSE file for details.