{"id":31559587,"url":"https://github.com/chocuuuu/hand-gesture-volume-control","last_synced_at":"2026-04-16T04:04:47.317Z","repository":{"id":314466560,"uuid":"1055582871","full_name":"chocuuuu/Hand-Gesture-Volume-Control","owner":"chocuuuu","description":"a simple cv project which controls the volume using only hand gestures","archived":false,"fork":false,"pushed_at":"2025-09-12T15:09:07.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-12T18:00:15.758Z","etag":null,"topics":["computer-vision","hand-gesture-volume-control","mediapipe","opencv","pycaw","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chocuuuu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T13:36:15.000Z","updated_at":"2025-09-12T15:11:06.000Z","dependencies_parsed_at":"2025-09-12T18:10:25.677Z","dependency_job_id":null,"html_url":"https://github.com/chocuuuu/Hand-Gesture-Volume-Control","commit_stats":null,"previous_names":["chocuuuu/hand-gesture-volume-control"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chocuuuu/Hand-Gesture-Volume-Control","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocuuuu%2FHand-Gesture-Volume-Control","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocuuuu%2FHand-Gesture-Volume-Control/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocuuuu%2FHand-Gesture-Volume-Control/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocuuuu%2FHand-Gesture-Volume-Control/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chocuuuu","download_url":"https://codeload.github.com/chocuuuu/Hand-Gesture-Volume-Control/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocuuuu%2FHand-Gesture-Volume-Control/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278399690,"owners_count":25980332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-vision","hand-gesture-volume-control","mediapipe","opencv","pycaw","python"],"created_at":"2025-10-05T01:54:21.907Z","updated_at":"2025-10-05T01:54:31.402Z","avatar_url":"https://github.com/chocuuuu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hand Gesture Volume Control\na simple cv project which controls the volume using only hand gestures\n\n# Gesture Volume Control (Python + OpenCV + MediaPipe)\n\nControl system volume with hand gestures:  \n- **Pinch between thumb tip and index tip** → set volume.  \n- **Wave hand side-to-side (“bye” gesture)** → exit the app.  \n\nBuilt with **OpenCV** for video capture/visualization, **MediaPipe Hands** for landmark tracking, and **pycaw** (Windows) for volume control.\n\n---\n\n## ✨ Features\n- Real-time hand tracking via MediaPipe Hands (21 landmarks per hand).\n- Volume mapped from the distance between thumb tip (`id 4`) and index tip (`id 8`).\n- Visual overlay: landmarks, pinch line, volume bar, and percentage.\n- “Bye” gesture: wave the hand left-right about 3 times to close the app.\n\n---\n\n## 🎬 Demo\n- **Volume control**: pinch thumb and index → closer lowers volume, wider increases volume.  \n- **Exit gesture**: wave hand side-to-side (≈3 oscillations within a few seconds) → app exits cleanly.\n\n---\n\n## 📂 Project Structure\nsrc/   \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; - main.py # Application entry point (video loop, volume mapping, wave-to-exit)  \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; - hand_control.py # MediaPipe utilities (landmarks, distance, helpers)  \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; - requirements.txt # Dependencies (opencv-python, mediapipe, numpy, pycaw/comtypes on Windows)  \n\n---\n\n## ⚙️ Requirements\n- Python **3.8–3.12** recommended.\n- **Windows**: requires `pycaw` + `comtypes` for system volume control.  \n- **macOS/Linux**: needs alternate backends (e.g., `osascript` or `pulsectl`).\n\n---\n\n## 📦 Installation\n\n### 1. Create \u0026 activate a virtual environment\n**Windows (PowerShell):**\n```\npowershell\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\n```\n\n### 2. Install dependencies\n```\npip install --upgrade pip setuptools wheel\npip install -r requirements.txt\n```\n✅ Use opencv-python (not cv2) in requirements.  \n⚠️ If you see warnings like Ignoring invalid distribution ~ip, delete stray ~ folders in site-packages and reinstall.\n\n---\n\n### ▶️ Running\n\nFrom the repository root with the virtual environment active:\n```\npython src/main.py\n```\nOn first run, allow webcam access if prompted.  \nA window titled “Gesture Volume Control” should appear.  \nPress ESC to exit as a fallback.  \n\n---\n\n### 🎮 Usage\n\n\u003e **Volume control**\n- Move thumb and index apart to raise volume, pinch closer to lower.\n- Linear mapping with smoothing reduces jitter.\n\n\u003e **Exit gesture**\n- Wave hand left-right across the frame center ≈3 times → triggers clean shutdown.\n\n---\n\n### ⚡Configuration\n\n- Edit constants in src/main.py to tune behavior:\n- Pinch distance mapping\n- DIST_MIN, DIST_MAX: pixel range (calibrate using observed pinch/spread).\n- SMOOTH_ALPHA: smoothing factor (0.2–0.5 recommended).\n- Wave detector (detect_wave)\n- min_amp (default 0.12): minimum horizontal swing.\n- min_period (default 0.15 s): debounce between direction changes.\n- window_s (default 3.0 s): rolling time window.\n- needed_alternations (default 3): oscillations required to exit.\n\n---\n\n### 🖥️ Platform Notes\n\n\u003e Windows: pycaw controls master volume via Core Audio.\n\u003e macOS/Linux: replace volume-control logic with a backend such as:\n\u003e macOS → osascript\n\u003e Linux → pulsectl\n\nHand tracking and UI logic remain the same.\n\n---\n\n### 🔍 How It Works\nMediaPipe Hands returns 21 landmarks per hand.\n\n- Wrist → id 0\n- Thumb tip → id 4\n- Index tip → id 8\n\n\u003e Volume mapping: distance between id 4 and id 8 → system volume range.  \n\u003e\u003e Linear mapping + exponential smoothing improves stability.\n\u003e\u003e \n\u003e Wave detector: monitors wrist x position, normalizes by frame width, counts left/right crossings, exits after enough oscillations.  \n\n---\n\n### 🙌 Credits \u0026 References\n- MediaPipe Hands documentation (landmark indexing \u0026 usage).\n- Prior art: gesture-based volume control with Python + OpenCV + MediaPipe + pycaw.\n\n---\n\n### 📸 Demo Media\n\nhttps://github.com/user-attachments/assets/b3075ad3-e4dc-40c1-a45c-40ec397ac0bb\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocuuuu%2Fhand-gesture-volume-control","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchocuuuu%2Fhand-gesture-volume-control","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocuuuu%2Fhand-gesture-volume-control/lists"}