# pramzie/air-piano architecture

> Architecture diagram of the GitHub repository pramzie/air-piano, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pramzie/air-piano
- Repository: https://github.com/pramzie/air-piano

## Overview

##### Project Type and Purpose
- This project is a specialized computer vision and MIDI synthesis application. Its primary function is to detect hand gestures using a webcam and computer vision libraries (OpenCV and cvzone) and translate these gestures into MIDI signals using pygame.midi, specifically to play chords in the D scale.
- The README clearly states it operates as a hand-tracking MIDI controller with automatic sustain for notes, making it both an interactive musical instrument and a demonstration of gesture-controlled interfaces.

##### Analyzing the File Structure
- Chord_mapping.txt: Likely contains the mapping between different hand/finger gestures and the corresponding D scale chords.
- hand_dscale.py: The main Python script coordinating the hand tracking, gesture recognition, and MIDI output.
- README.md: Contains the project description, features, and high-level overview.
- requirements01.txt: Lists the dependencies not only to set up the development environment but also indicates the external libraries used (such as OpenCV, cvzone, and pygame.midi).

##### Main Components
a. Input/Acquisition Layer:
- Webcam/Capture Module: Represents the video input device from which frames are captured.

b. Vision Processing & Hand Tracking Module:
- OpenCV and cvzone integration that processes the video stream to detect hand gestures.
- This module represents the computer vision pipeline to extract finger positions and gestures.

c. Gesture-to-Chord Mapping:
- Chord Mapping Component: A logical module that loads the chord mappings from Chord_mapping.txt and maps detected gestures to the correct D scale chords.

d. MIDI Output Module:
- Pygame MIDI Module: Handles the generation and transmission of MIDI signals to simulate piano sounds. This module also implements the automatic sustain for 2 seconds.

e. Control & Orchestration:
- Main Application Logic within hand_dscale.py that ties all the above modules together, managing the capture of video frames, gesture detection, chord mapping, and MIDI signal output.

f. Dependency/Configuration Management:
- Dependencies listed in requirements01.txt, indicating the external libraries used.

##### Relationships and Data Flow
- Input flows from the Webcam to the Vision Processing module.
- The Vision Processing module outputs recognized hand or finger positions.
- These positions are sent to the Gesture-to-Chord Mapping module which decides which chord (from the D scale) is indicated.
- The decision is then passed to the MIDI Output Module, which uses pygame.midi to send the MIDI signals.
- A feedback loop to account for the automatic sustain (notes continue for a fixed duration and then stop).

##### Important Architectural Patterns and Technologies
- Modular Design: Each module (input, processing, mapping, and MIDI output) is logically separated, which helps in understanding dependencies and future extensibility.
- Event Flow: Gestures trigger events leading to MIDI outputs.
- Technologies included: Python, OpenCV, cvzone, pygame.midi.
- The system might not be highly layered due to its simplicity; instead, it uses a linear data processing pipeline from capture to output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Controller and Configuration
    AC["Application Controller"]:::controller
    DEP["Dependencies/Configuration"]:::config

    %% Processing Pipeline Subgraph
    subgraph "Processing Pipeline" [Processing Pipeline]
        WCI["Webcam Input"]:::hardware
        HT["Hand Tracking (OpenCV/cvzone)"]:::processing
        GC["Gesture-to-Chord Mapper"]:::processing
        MO["MIDI Output (pygame.midi)"]:::output
    end

    %% Sustain Logic Note
    SUSTAIN["Sustain Logic (2sec hold)"]:::note

    %% Data Flow
    AC -->|"initiates"| WCI
    WCI -->|"captures frames"| HT
    HT -->|"detects gestures"| GC
    GC -->|"maps to chords"| MO
    MO -->|"applies sustain"| SUSTAIN
    AC -->|"loads dependencies"| DEP

    %% Click Events
    click WCI "https://github.com/pramzie/air-piano/blob/main/hand_dscale.py"
    click HT "https://github.com/pramzie/air-piano/blob/main/hand_dscale.py"
    click GC "https://github.com/pramzie/air-piano/blob/main/Chord_mapping.txt"
    click MO "https://github.com/pramzie/air-piano/blob/main/hand_dscale.py"
    click AC "https://github.com/pramzie/air-piano/blob/main/hand_dscale.py"
    click DEP "https://github.com/pramzie/air-piano/blob/main/requirements01.txt"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef processing fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef output fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef controller fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef note fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
