https://github.com/chocuuuu/hand-gesture-volume-control
a simple cv project which controls the volume using only hand gestures
https://github.com/chocuuuu/hand-gesture-volume-control
computer-vision hand-gesture-volume-control mediapipe opencv pycaw python
Last synced: 3 months ago
JSON representation
a simple cv project which controls the volume using only hand gestures
- Host: GitHub
- URL: https://github.com/chocuuuu/hand-gesture-volume-control
- Owner: chocuuuu
- Created: 2025-09-12T13:36:15.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-12T15:09:07.000Z (10 months ago)
- Last Synced: 2025-09-12T18:00:15.758Z (10 months ago)
- Topics: computer-vision, hand-gesture-volume-control, mediapipe, opencv, pycaw, python
- Language: Python
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hand Gesture Volume Control
a simple cv project which controls the volume using only hand gestures
# Gesture Volume Control (Python + OpenCV + MediaPipe)
Control system volume with hand gestures:
- **Pinch between thumb tip and index tip** → set volume.
- **Wave hand side-to-side (“bye” gesture)** → exit the app.
Built with **OpenCV** for video capture/visualization, **MediaPipe Hands** for landmark tracking, and **pycaw** (Windows) for volume control.
---
## ✨ Features
- Real-time hand tracking via MediaPipe Hands (21 landmarks per hand).
- Volume mapped from the distance between thumb tip (`id 4`) and index tip (`id 8`).
- Visual overlay: landmarks, pinch line, volume bar, and percentage.
- “Bye” gesture: wave the hand left-right about 3 times to close the app.
---
## 🎬 Demo
- **Volume control**: pinch thumb and index → closer lowers volume, wider increases volume.
- **Exit gesture**: wave hand side-to-side (≈3 oscillations within a few seconds) → app exits cleanly.
---
## 📂 Project Structure
src/
- main.py # Application entry point (video loop, volume mapping, wave-to-exit)
- hand_control.py # MediaPipe utilities (landmarks, distance, helpers)
- requirements.txt # Dependencies (opencv-python, mediapipe, numpy, pycaw/comtypes on Windows)
---
## ⚙️ Requirements
- Python **3.8–3.12** recommended.
- **Windows**: requires `pycaw` + `comtypes` for system volume control.
- **macOS/Linux**: needs alternate backends (e.g., `osascript` or `pulsectl`).
---
## 📦 Installation
### 1. Create & activate a virtual environment
**Windows (PowerShell):**
```
powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```
### 2. Install dependencies
```
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
```
✅ Use opencv-python (not cv2) in requirements.
⚠️ If you see warnings like Ignoring invalid distribution ~ip, delete stray ~ folders in site-packages and reinstall.
---
### ▶️ Running
From the repository root with the virtual environment active:
```
python src/main.py
```
On first run, allow webcam access if prompted.
A window titled “Gesture Volume Control” should appear.
Press ESC to exit as a fallback.
---
### 🎮 Usage
> **Volume control**
- Move thumb and index apart to raise volume, pinch closer to lower.
- Linear mapping with smoothing reduces jitter.
> **Exit gesture**
- Wave hand left-right across the frame center ≈3 times → triggers clean shutdown.
---
### ⚡Configuration
- Edit constants in src/main.py to tune behavior:
- Pinch distance mapping
- DIST_MIN, DIST_MAX: pixel range (calibrate using observed pinch/spread).
- SMOOTH_ALPHA: smoothing factor (0.2–0.5 recommended).
- Wave detector (detect_wave)
- min_amp (default 0.12): minimum horizontal swing.
- min_period (default 0.15 s): debounce between direction changes.
- window_s (default 3.0 s): rolling time window.
- needed_alternations (default 3): oscillations required to exit.
---
### 🖥️ Platform Notes
> Windows: pycaw controls master volume via Core Audio.
> macOS/Linux: replace volume-control logic with a backend such as:
> macOS → osascript
> Linux → pulsectl
Hand tracking and UI logic remain the same.
---
### 🔍 How It Works
MediaPipe Hands returns 21 landmarks per hand.
- Wrist → id 0
- Thumb tip → id 4
- Index tip → id 8
> Volume mapping: distance between id 4 and id 8 → system volume range.
>> Linear mapping + exponential smoothing improves stability.
>>
> Wave detector: monitors wrist x position, normalizes by frame width, counts left/right crossings, exits after enough oscillations.
---
### 🙌 Credits & References
- MediaPipe Hands documentation (landmark indexing & usage).
- Prior art: gesture-based volume control with Python + OpenCV + MediaPipe + pycaw.
---
### 📸 Demo Media
https://github.com/user-attachments/assets/b3075ad3-e4dc-40c1-a45c-40ec397ac0bb