# vash-codex/airsynth architecture

> Architecture diagram of the GitHub repository vash-codex/airsynth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vash-codex/airsynth
- Repository: https://github.com/vash-codex/airsynth

## Overview

Air Piano is a contactless instrument: hand distance is sensed by an Arduino setup, sent to a Python application, and translated into chromatic piano sounds with visual feedback. The sampled Python file combines serial input, note selection and playback, and the animated interface in one runtime loop, so those responsibilities share its source path. The README documents the Arduino and audio capabilities, but the Arduino source was not sampled; its connections are shown as documented or unverified.

Main entry points: [`airpianomain.py`](https://github.com/vash-codex/airsynth/blob/main/airpianomain.py) (Serial input), [`airpiano.ino`](https://github.com/vash-codex/airsynth/blob/main/airpiano.ino) (Arduino controller), [`wav`](https://github.com/vash-codex/airsynth/tree/main/wav) (Piano WAVs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Distance sensing"]
  node_sensor["Ultrasonic sensor"]
  node_arduino["Arduino controller<br/>[airpiano.ino]"]
end

subgraph group_app["Piano application"]
  node_serial_input["Serial input<br/>[airpianomain.py]"]
  node_note_queue["Note queue<br/>[airpianomain.py]"]
  node_sound_playback["Note playback<br/>[airpianomain.py]"]
  node_visual_interface["Animated interface<br/>[airpianomain.py]"]
end

subgraph group_audio["Piano audio"]
  node_wav_files["Piano WAVs"]
end

node_hand(("Player hand"))

node_hand -->|"changes distance"| node_sensor
node_sensor -.->|"measures distance"| node_arduino
node_arduino -.->|"sends readings"| node_serial_input
node_serial_input -->|"queues notes"| node_note_queue
node_note_queue -->|"plays next"| node_sound_playback
node_wav_files -->|"provides samples"| node_sound_playback
node_serial_input -->|"updates distance"| node_visual_interface
node_sound_playback -->|"drives note feedback"| node_visual_interface

click node_arduino "https://github.com/vash-codex/airsynth/blob/main/airpiano.ino"
click node_serial_input "https://github.com/vash-codex/airsynth/blob/main/airpianomain.py"
click node_note_queue "https://github.com/vash-codex/airsynth/blob/main/airpianomain.py"
click node_sound_playback "https://github.com/vash-codex/airsynth/blob/main/airpianomain.py"
click node_wav_files "https://github.com/vash-codex/airsynth/tree/main/wav"
click node_visual_interface "https://github.com/vash-codex/airsynth/blob/main/airpianomain.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sensor,node_arduino toneBlue
class node_serial_input,node_note_queue,node_sound_playback,node_visual_interface toneAmber
class node_wav_files toneMint
class node_hand toneIndigo
```

## Components

### Distance sensing

- **Ultrasonic sensor**
- [Arduino controller](https://github.com/vash-codex/airsynth/blob/main/airpiano.ino): `airpiano.ino`

### Piano application

- [Serial input](https://github.com/vash-codex/airsynth/blob/main/airpianomain.py): `airpianomain.py`
- [Note queue](https://github.com/vash-codex/airsynth/blob/main/airpianomain.py): `airpianomain.py`
- [Note playback](https://github.com/vash-codex/airsynth/blob/main/airpianomain.py): `airpianomain.py`
- [Animated interface](https://github.com/vash-codex/airsynth/blob/main/airpianomain.py): `airpianomain.py`

### Piano audio

- [Piano WAVs](https://github.com/vash-codex/airsynth/tree/main/wav): `wav`

### Other components

- **Player hand**

## Connections

- Player hand → Ultrasonic sensor: changes distance (evidence: `README.md`)
- Ultrasonic sensor → Arduino controller: measures distance
- Arduino controller → Serial input: sends readings (evidence: `README.md`)
- Serial input → Note queue: queues notes (evidence: `airpianomain.py`)
- Note queue → Note playback: plays next (evidence: `airpianomain.py`)
- Piano WAVs → Note playback: provides samples (evidence: `README.md`)
- Serial input → Animated interface: updates distance (evidence: `airpianomain.py`)
- Note playback → Animated interface: drives note feedback (evidence: `airpianomain.py`)
