How lemon-2-ade/volume-controller works
Project type and purpose
• This is a standalone desktop utility (an open-source tool) written in Python.
• Purpose: capture webcam input, detect hand gestures (distance between thumb and index finger), map that distance to system volume, and provide real-time visual feedback.
File structure
• Top-level scripts:
• hand_detector.py – encapsulates MediaPipe hand landmark detection logic.
• main.py – orchestrates video capture, gesture processing, volume adjustment, and UI overlay.
• requirements.txt – lists Python dependencies (OpenCV, MediaPipe, pycaw, numpy, etc.).
• README.md – describes usage, features, and architecture at a high level.
README for additional insights
• Uses OpenCV for video I/O and on-screen display.
• Uses MediaPipe for hand tracking.
• Uses pycaw to interact with the Windows Core Audio API.
• Maps landmark distance to volume via numpy interpolation (np.interp).
Components and relationships
a. Main Components
1. Video Capture Module (OpenCV VideoCapture)
2. Hand Detection Module (MediaPipe, implemented in hand_detector.py)
3. Distance Calculation & Mapping (Numpy interpolation)
4. Audio Control Module (pycaw wrappers)
5. UI Overlay (OpenCV drawing functions)
6. Operating System Audio Subsystem (Windows Core Audio API)
b. Interactions / Data Flow
1. Webcam → Video Capture Module → raw frame
2. raw frame → Hand Detection Module → landmarks (thumb & index finger coordinates)
3. landmarks → Distance & Mapping → volume level (0–100%)
4. volume level → Audio Control Module → OS Audio Subsystem (set system volume)
5. raw frame + landmarks + volume level → UI Overlay → display window
c. Architectural Patterns / Principles
• Pipeline pattern: sequential processing of video frames.
• Modular separation: detection logic (hand_detector.py) is decoupled from orchestration and I/O (main.py).
• Single-responsibility: each module only handles one concern (capture, detection, mapping, control, display).
d. Key technologies
• OpenCV (cv2) – video I/O, drawing UI
• MediaPipe – hand landmark detection
• numpy – interpolation math
• pycaw – Windows audio API binding
• Python 3 runtime