# lemon-2-ade/volume-controller architecture

> Architecture diagram of the GitHub repository lemon-2-ade/volume-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lemon-2-ade/volume-controller
- Repository: https://github.com/lemon-2-ade/volume-controller

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware I/O
    Webcam["Webcam"]:::hardware
    %% Processing Modules
    VideoCapture["VideoCapture (OpenCV)"]:::processing
    HandDetector["HandDetector (MediaPipe)"]:::processing
    DistanceMapper["DistanceMapper (numpy interp)"]:::processing
    AudioController["AudioController (pycaw)"]:::processing
    %% OS Audio API
    WindowsAudioAPI(("Windows Audio API")):::osapi
    %% UI Components
    UIOverlay["UIOverlay (OpenCV draw)"]:::ui
    DisplayWindow["Display Window"]:::ui
    %% Documentation
    README["README.md"]:::docs
    Requirements["requirements.txt"]:::docs

    %% Data Flow
    Webcam -->|"video frame"| VideoCapture
    VideoCapture -->|"raw frame"| HandDetector
    HandDetector -->|"landmarks"| DistanceMapper
    DistanceMapper -->|"volume %"| AudioController
    AudioController -->|"set volume"| WindowsAudioAPI

    %% UI Flow
    VideoCapture -->|"raw frame"| UIOverlay
    HandDetector -->|"landmarks"| UIOverlay
    DistanceMapper -->|"volume %"| UIOverlay
    UIOverlay -->|"render"| DisplayWindow

    %% Click Events
    click VideoCapture "https://github.com/lemon-2-ade/volume-controller/blob/main/main.py"
    click HandDetector "https://github.com/lemon-2-ade/volume-controller/blob/main/hand_detector.py"
    click DistanceMapper "https://github.com/lemon-2-ade/volume-controller/blob/main/main.py"
    click AudioController "https://github.com/lemon-2-ade/volume-controller/blob/main/main.py"
    click UIOverlay "https://github.com/lemon-2-ade/volume-controller/blob/main/main.py"
    click README "https://github.com/lemon-2-ade/volume-controller/blob/main/README.md"
    click Requirements "https://github.com/lemon-2-ade/volume-controller/blob/main/requirements.txt"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000;
    classDef processing fill:#90EE90,stroke:#000;
    classDef ui fill:#FFA500,stroke:#000;
    classDef osapi fill:#B0C4DE,stroke:#000,stroke-dasharray: 5 5;
    classDef docs fill:#F0F0F0,stroke:#000,stroke-dasharray: 2 2;
```
