Control your PC with hand gestures via webcam.
MouseSpot acts as a low-latency, strictly offline hand-tracking mouse overlay. Native Wayland/X11 bindings allow seamless, system-level cursor control without being constrained to a single application window.
output.mp4
We exclusively use uv for lightning fast Python environment management.
# 1. Clone the repository
git clone https://github.com/yourusername/MouseSpot.git
cd MouseSpot
# 2. Install dependencies silently
uv sync
# 3. Launch the application
uv run mousespotThe tracker algorithms map your gestures to instant OS mouse actions:
| Gesture | Hand Shape | Action |
|---|---|---|
| FREEZE | Tight Fist | Pause cursor movement and tracking. |
| POINTER | Only Index Finger Extended | Moves the mouse cursor. |
| LEFT CLICK | Index tip touching Thumb tip | Emits a single Left-Click. |
| DOUBLE CLICK | Double Index-Thumb Pinch | Emits a Double Left-Click. |
| RIGHT CLICK | Middle tip touching Thumb tip | Emits a single Right-Click. |
| SCROLL MODE | Index & Middle Fingers Extended (Peace) | Moving your hand up or down scrolls via wheel ticks. |
You might encounter importing exceptions depending on the underlying OS headers.
Ensure you have successfully synced virtual environment using uv sync. Open CV requires some graphical libraries so if you are running headless or minimal ubuntu, you might need:
sudo apt-get update
sudo apt-get install libgl1 -ySince MouseSpot issues native system-wide clicks, Wayland specifically enforces security domains.
If you are running Wayland ($XDG_SESSION_TYPE=wayland), ensure you have write permissions to uinput:
- Check if the backend auto-resolves successfully inside
uv run mousespot. - Ensure you are in the
inputgroup:sudo usermod -aG input $USER # You must log out and log back in for groups to refresh!
Pull requests are actively welcomed! Please note that all code must pass rigorous type-checking and linting workflows.
uv run ruff check src/ tests/
uv run mypy src/ tests/
uv run pytest tests/Before submitting large features, please open an Issue to track discussions!
Distributed beneath the MIT License. See LICENSE for more information.