Mouseless

ভার্চুয়াল মাউস ইউজিং হ্যান্ড মোশন

"হাত না থাকলেও স্বপ্ন থাকে – আমরা সেই স্বপ্নকে কার্সার বানিয়ে দিই"

Mouseless is Bangladesh's first hand-gesture virtual mouse system — no physical mouse required. Control your computer using only hand gestures captured through any standard webcam, completely offline.

Features · Installation · Usage · Modes · License · Contact

🎯 About the Project

Mouseless was built with one belief:

No child in Bangladesh should be told "you cannot use a computer because you cannot hold a mouse."

Mouseless is a 100% offline, AI-powered virtual mouse that works through any standard webcam. It supports multiple control modes including two-hand, one-hand, one-finger, and (coming soon) head-control — making computers accessible to everyone.


Official Project ID	`27022251146`
Official Project Name	ভার্চুয়াল মাউস ইউজিং হ্যান্ড মোশন
Brand	Mouseless by asikdial.tech

✨ Features

Feature	Status
🖐 Two-hand gesture control (standard)	✅ Available
🤚 One-hand mode	✅ Available
☝️ One-finger mode (accessibility)	✅ Available
🗣 Bangla voice feedback	🔜 Coming Soon
👤 Head-control mode	🔜 Coming Soon
⚙️ Live cursor speed / scroll adjustment	✅ Available
📷 Camera selection from UI	✅ Available
💾 Settings auto-saved (settings.json)	✅ Available
🔑 License key system	✅ Available
📊 Action feedback in UI	✅ Available
🌐 100% offline – no internet needed	✅ Available
🏫 School dashboard	🔜 Coming Soon

💻 System Requirements

Component	Minimum	Recommended
OS	Windows 10 / Ubuntu 20.04 / macOS 12	Windows 11 / Ubuntu 22.04 / macOS 14
Python	3.11.x	3.11.x (strictly required)
RAM	4 GB	8 GB
CPU	Dual-core 2.0 GHz	Quad-core 2.5 GHz+
Camera	Any USB / built-in webcam	720p or higher
Storage	500 MB free	1 GB free
Display	1024 × 768	1920 × 1080

⚠️ Python 3.11 is strictly required. MediaPipe is not yet stable on Python 3.12 or 3.13. Using any other version may cause unexpected errors.

📦 Dependencies

All dependencies are managed automatically by uv. For reference, these are the packages used:

Package	Purpose
`opencv-python`	Camera capture & frame processing
`mediapipe`	Hand landmark detection (AI model)
`pyautogui`	Mouse and keyboard simulation
`PySide6`	Modern desktop GUI framework
`pycaw`	Windows system volume control
`comtypes`	Windows COM interface (required by pycaw)
`screen-brightness-control`	System brightness control
`protobuf`	MediaPipe internal data format

ℹ️ pycaw and comtypes are Windows-only. On Linux and macOS they are skipped automatically. All other features work on all platforms.

🚀 Installation

We use uv — an ultra-fast Python package manager written in Rust. It is 10–100× faster than pip and manages Python versions automatically. You do not need to install Python separately — uv handles it.

🪟 Windows

Open PowerShell for all steps below. Search "PowerShell" in the Start Menu to open it.

Step 1 — Install uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close PowerShell completely and open a new PowerShell window.

Verify the installation:

uv --version

Expected output: uv 0.x.x (any version is fine)

Step 2 — Install Python 3.11

uv python install 3.11

Verify:

uv python list

You should see 3.11.x in the list.

Step 3 — Get the project

If you have Git installed:

git clone https://github.com/your-username/mouseless.git
cd mouseless

If you do not have Git:

Download the project as a ZIP file from GitHub
Extract the ZIP to any folder (e.g. C:\mouseless)
Open PowerShell and navigate to that folder:

cd C:\mouseless

Step 4 — Install all dependencies

uv sync

This will automatically:

Create a virtual environment inside .venv
Install all required packages from pyproject.toml
Lock the exact versions in uv.lock

If you are setting up a completely fresh project without a lock file:

uv add opencv-python mediapipe pyautogui PySide6 pycaw comtypes screen-brightness-control protobuf

Step 5 — Run Mouseless

uv run run.py

✅ The Mouseless launcher window will open immediately.

Windows — Camera Permission Check

If the camera does not open, check:

Windows Settings → Privacy & Security → Camera
→ Camera access: ON
→ Allow desktop apps to access your camera: ON

🐧 Linux (Ubuntu / Debian)

Open your Terminal for all steps below.

Step 1 — Install system dependencies

sudo apt update && sudo apt install -y \
    curl \
    git \
    python3-dev \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    libgl1-mesa-glx \
    libportaudio2 \
    libxcb-cursor0 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-shape0

Step 2 — Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your shell configuration:

source ~/.bashrc

If you use Zsh:

source ~/.zshrc

Verify:

uv --version

Step 3 — Install Python 3.11

uv python install 3.11

Step 4 — Get the project

git clone https://github.com/your-username/mouseless.git
cd mouseless

Step 5 — Fix camera permissions

sudo usermod -aG video $USER

⚠️ You must log out and log back in after running this command for the permission change to take effect.

Step 6 — Install all dependencies

uv sync

Or for a fresh setup:

uv add opencv-python mediapipe pyautogui PySide6 \
       screen-brightness-control protobuf

ℹ️ Do not add pycaw or comtypes on Linux — they are Windows-only. Mouseless will automatically disable volume control on Linux. All other features (cursor, click, scroll, brightness) work fully.

Step 7 — Run Mouseless

uv run run.py

✅ The Mouseless launcher window will open.

🍎 macOS

Open your Terminal for all steps below. Terminal is found in: Applications → Utilities → Terminal

Step 1 — Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, follow any instructions shown in the terminal to add Homebrew to your PATH.

Step 2 — Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Reload your shell:

source ~/.zshrc

Verify:

uv --version

Step 3 — Install Python 3.11

uv python install 3.11

Step 4 — Get the project

git clone https://github.com/your-username/mouseless.git
cd mouseless

Step 5 — Grant camera permission

Go to:

System Settings → Privacy & Security → Camera

Make sure Terminal has camera access set to ON.

If you run Mouseless from an IDE (e.g. VS Code), grant camera access to that application instead.

Step 6 — Install all dependencies

uv sync

Or for a fresh setup:

uv add opencv-python mediapipe pyautogui PySide6 \
       screen-brightness-control protobuf

ℹ️ Do not add pycaw or comtypes on macOS — they are Windows-only. Volume control gestures are automatically disabled on macOS. All other features work fully.

Step 7 — Run Mouseless

uv run run.py

✅ The Mouseless launcher window will open.

▶️ Running the App

After installation, always run from the project root folder:

uv run run.py

First launch — License setup

On the very first launch, you will see this prompt in the terminal:

=== Mouseless License Setup ===
Press Enter for Free Personal License
or enter a school / institution key:

Press Enter → continues with the Free Personal License
Type a school key and press Enter → activates that license

Your choice is saved in license.json and will not be asked again.

Stopping Mouseless

Press q inside the camera window, or
Click the Stop button in the launcher

🎮 Control Modes

Select your mode from the Control Mode dropdown in the launcher window. Changes are saved automatically.

🖐 Two Hands — Standard

Best accuracy · Recommended for first-time users

Hand	Controls
Dominant hand (right by default)	Cursor move · Left click · Drag · Double click · Right click
Non-dominant hand (left by default)	Scroll · Volume · Brightness

🤚 One Hand

For users who prefer single-hand operation

One hand controls everything: move · click · drag · scroll · volume · brightness

☝️ One Finger — Experimental

Designed for users with limited hand mobility

Action	Gesture
Move cursor	Raise exactly one finger
Left click	Make a FIST → then raise one finger (tap)
Stop / Idle	Full FIST or open PALM
Two or more fingers	Cursor stops (ignored)

👤 Head Control — Coming Soon

For users who cannot use their hands at all

Head movement → cursor movement
Eye blink or dwell-time → click
Will use MediaPipe Face Mesh (no extra hardware needed)

🤌 Gesture Reference

Applies to Two Hands and One Hand modes.

Gesture	Action
✌️ V-sign (index + middle finger open)	Move cursor
✊ Closed fist (hold)	Click and hold (drag)
🤙 Pinch — dominant hand	Volume UP / DOWN · Brightness UP / DOWN
🤙 Pinch — non-dominant hand	Scroll UP / DOWN · Scroll LEFT / RIGHT
☝️ Index finger only (after V-sign)	Right click
🤞 Two fingers closed (after V-sign)	Double click
🖐 Open palm	Idle — cursor stops

📁 Project Structure

mouseless/
│
├── run.py                          ← Entry point  →  uv run run.py
├── pyproject.toml                  ← uv project config + dependencies
├── .python-version                 ← Locks Python 3.11
├── .gitignore                      ← Git ignore rules
├── README.md                       ← This file
│
├── mouseless_core/                 ← Gesture engine (no UI)
│   ├── __init__.py
│   ├── config.py                   ← All tunable parameters
│   ├── modes.py                    ← Control mode definitions
│   ├── gestures.py                 ← Gesture enums (binary encoded)
│   ├── hand_recognition.py         ← MediaPipe → gesture conversion
│   ├── controller.py               ← Gesture → OS action dispatch
│   ├── app.py                      ← Camera loop + mode routing
│   ├── licensing.py                ← License key validation + storage
│   ├── settings_manager.py         ← Load / save settings.json
│   └── action_feedback.py          ← Event logging + UI callback bridge
│
└── mouseless_ui/                   ← Desktop GUI
    ├── __init__.py
    ├── styles.py                   ← Centralised QSS stylesheet
    └── launcher.py                 ← PySide6 launcher window

⚙️ Configuration

You can adjust default values in mouseless_core/config.py:

# ── Camera ───────────────────────────────────────────
CAMERA_INDEX = 0            # 0 = built-in camera, 1 = first USB camera

# ── Cursor ───────────────────────────────────────────
CURSOR_SMOOTHING_ALPHA  = 0.6   # 0.1 (very smooth) → 1.0 (instant/raw)
CURSOR_SPEED_MULTIPLIER = 1.0   # overridden live by the UI slider

# ── Scroll ───────────────────────────────────────────
SCROLL_STEP = 120               # scroll amount per pinch event

# ── Gesture sensitivity ──────────────────────────────
PINCH_THRESHOLD = 0.3           # minimum movement to trigger pinch

All settings changed through the launcher UI are saved automatically to settings.json and restored on next launch. You do not need to edit config.py for normal use.

🔑 License Keys

Key	Type	Cost
(none — press Enter)	Free Personal License	Free forever
`MOUSELESS-PERSONAL-2025-FREE`	Registered Personal License	Free forever
`MOUSELESS-SCHOOL-TRIAL-2025`	School Trial License	Free (demo)
`MOUSELESS-SCHOOL-ANNUAL-2025`	School Annual License	Paid

Personal use is always free — no key or registration needed. For school / institutional licensing, contact us at contact@asikdial.tech.

🛠 Troubleshooting

Camera does not open

Symptom:

[ERROR] Could not open camera

Fix — Find available cameras:

import cv2
for i in range(5):
    cap = cv2.VideoCapture(i)
    print(f"Camera {i}:", "AVAILABLE" if cap.isOpened() else "not found")
    cap.release()

Save this as find_cameras.py and run:

uv run find_cameras.py

Then select the correct index in the Camera dropdown in the launcher.

Hand not being detected

Ensure lighting comes from in front of you, not from behind
Use a plain, single-colour background (white wall is ideal)
Keep your hand inside the camera frame at all times
Your hand should fill roughly 20–30% of the camera frame area
Avoid wearing gloves or very dark clothing that covers your hand

Cursor jumping or erratic movement

Lower the Cursor Speed slider to 0.80× or below
Check for bright reflective surfaces in the camera's field of view
Ensure no other application (Zoom, Teams, OBS) is using the camera
Try reducing ambient light sources behind you

`pycaw` import error on Linux or macOS

Symptom:

ModuleNotFoundError: No module named 'pycaw'

This is expected and normal. pycaw is a Windows-only package. Mouseless automatically disables volume control on Linux and macOS. No action is needed — everything else works normally.

PySide6 window does not open on Linux

sudo apt install -y \
    libxcb-cursor0 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-shape0

Then run again:

uv run run.py

MediaPipe is slow to load on first launch

The first launch always takes 5–15 seconds while MediaPipe loads its neural network model into memory. After that, all gesture detection runs in real time. This delay only happens once per session.

Settings not saving

Make sure the project folder is not inside a read-only location (e.g. C:\Program Files\ on Windows). Move the project to a regular folder such as C:\Users\YourName\mouseless\.

`uv sync` fails with dependency errors

Try clearing the uv cache and syncing again:

uv cache clean
uv sync

📄 License

Mouseless Software License

Personal Use   —  Free forever, no restrictions
Educational    —  Trial available; annual institutional license available
Commercial     —  Contact for pricing and terms

This software is provided "as is" without warranty of any kind.
The author is not liable for any damages arising from the use of this software.

© Copyright

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   Copyright © 2025 Mouseless                                 ║
║   Powered by asikdial.tech                                   ║
║   All rights reserved.                                       ║
║                                                              ║
║   Official Project ID   :  27022251146                       ║
║   Official Project Name :  ভার্চুয়াল মাউস ইউজিং হ্যান্ড মোশন  ║
║   Brand                 :  Mouseless                         ║
║   Website               :  https://asikdial.tech             ║
║   Email                 :  contact@asikdial.tech             ║
║                                                              ║
║   Unauthorised copying, redistribution, or modification      ║
║   of this software without written permission from the       ║
║   copyright holder is strictly prohibited.                   ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

📬 Contact

Channel	Details
🌐 Website	asikdial.tech
📧 Email	asikdial.tech@gmail.com
💼 GitHub	github.com/asikdial-tech/mouseless

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
mouseless_core		mouseless_core
mouseless_ui		mouseless_ui
LICENSE		LICENSE
README.md		README.md
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation

Mouseless

ভার্চুয়াল মাউস ইউজিং হ্যান্ড মোশন

📋 Table of Contents

🎯 About the Project

✨ Features

💻 System Requirements

📦 Dependencies

🚀 Installation

🪟 Windows

Step 1 — Install uv

Step 2 — Install Python 3.11

Step 3 — Get the project

Step 4 — Install all dependencies

Step 5 — Run Mouseless

Windows — Camera Permission Check

🐧 Linux (Ubuntu / Debian)

Step 1 — Install system dependencies

Step 2 — Install uv

Step 3 — Install Python 3.11

Step 4 — Get the project

Step 5 — Fix camera permissions

Step 6 — Install all dependencies

Step 7 — Run Mouseless

🍎 macOS

Step 1 — Install Homebrew (if not already installed)

Step 2 — Install uv

Step 3 — Install Python 3.11

Step 4 — Get the project

Step 5 — Grant camera permission

Step 6 — Install all dependencies

Step 7 — Run Mouseless

▶️ Running the App

First launch — License setup

Stopping Mouseless

🎮 Control Modes

🖐 Two Hands — Standard

🤚 One Hand

☝️ One Finger — Experimental

👤 Head Control — Coming Soon

🤌 Gesture Reference

📁 Project Structure

⚙️ Configuration

🔑 License Keys

🛠 Troubleshooting

Camera does not open

Hand not being detected

Cursor jumping or erratic movement

pycaw import error on Linux or macOS

PySide6 window does not open on Linux

MediaPipe is slow to load on first launch

Settings not saving

uv sync fails with dependency errors

📄 License

© Copyright

📬 Contact

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`pycaw` import error on Linux or macOS

`uv sync` fails with dependency errors

Packages