# zivkovicmilos/pianoplayer architecture

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

- Interactive diagram: https://gitdiagram.com/zivkovicmilos/pianoplayer
- Repository: https://github.com/zivkovicmilos/pianoplayer

## Overview

##### Project type and purpose
- Type: Stand-alone desktop application (Java Swing)
- Purpose: Load, display, play, record, and export piano compositions (VirtualPiano text or MIDI) using Java Sound API.

##### File structure
- src/pianosystem: all Java classes, grouped roughly by responsibility
- data/: static input files (map.csv, VirtualPiano .txt compositions)
- resources/imgs: GUI assets (play/pause/stop buttons, PSDs, logos)
- out/, artifacts/: compiled JAR and build outputs

##### Key insights from README
- MVC-style separation: Reader → Composition (Model) → View (NoteView, Piano) → Controller (Player/Recorder)
- Two input sources: CSV mapping for key→note, VirtualPiano text for compositions
- Two output targets: text export (VirtualPiano format) and MIDI export
- Playback uses Java Sound API

##### Main components
A. User Interface Layer (Blue)
– Main Window (Main.java)
– ControlBoard (play, pause, stop, record buttons)
– Piano View (Piano.java, WhiteKey/BlackKey)
– Dialogs (About.java, SaveDialog.java)
B. Controller Layer (Yellow)
– Main controller (Main.java orchestrates startup)
– Reader (Reader.java: parses map.csv and VirtualPiano text via regex)
– Player (Player.java: drives playback events)
– NotePlayer (NotePlayer.java: interacts with Java Sound API)
– Recorder (Recorder.java: captures live input events)
C. Model Layer (Green)
– Composition (Composition.java: ordered MusicSymbol list)
– MusicSymbol (MusicSymbol.java: wrapper for Note or Pause)
– Note (Note.java: pitch + octave)
– Duration (Duration.java: timing info)
D. Data & External Services (Red)
– Local files (data/map.csv, data/input/*.txt)
– Java Sound API (javax.sound.midi or javax.sound.sampled)
– File export modules (MIDI export, VirtualPiano TXT via SaveDialog)

##### Relationships and data flow
- On launch, Main initializes Reader → loads map.csv + composition file → builds Composition model
- UI renders Composition via NoteView and Piano
- User actions on ControlBoard trigger Player or Recorder
- Player drives NotePlayer to send MIDI events to Java Sound API → audio output
- Recorder captures keyboard/mouse events → stores MusicSymbols in Composition
- SaveDialog exports Composition to TXT or MIDI

##### Architectural patterns & design principles
- MVC (Model: Composition/MusicSymbol; View: NoteView/Piano/ControlBoard; Controller: Player/Recorder/Reader)
- Single-Module Java application: separation of concerns by package pianosystem
- Resource abstraction: externalize images and data under /resources and /data

##### Technologies & frameworks
- Java SE (Swing GUI, Streams, Regex)
- Java Sound API for playback/export
- Standard file I/O for reading .csv/.txt and writing .txt/.mid
- Build artifacts: single executable JAR (PianoPlayer.jar)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer (Blue)
    subgraph "User Interface"
        direction TB
        MainWindow["Main Window"]:::ui
        ControlBoard["ControlBoard"]:::ui
        Piano["Piano"]:::ui
        WhiteKey["WhiteKey"]:::ui
        BlackKey["BlackKey"]:::ui
        NoteView["NoteView"]:::ui
        AboutDialog["About"]:::ui
        SaveDialog["SaveDialog"]:::ui
    end

    %% Controller Layer (Yellow)
    subgraph "Controller"
        direction TB
        ReaderComp["Reader"]:::controller
        PlayerComp["Player"]:::controller
        NotePlayerComp["NotePlayer"]:::controller
        RecorderComp["Recorder"]:::controller
    end

    %% Model Layer (Green)
    subgraph "Model"
        direction TB
        CompositionComp["Composition"]:::model
        MusicSymbolComp["MusicSymbol"]:::model
        NoteComp["Note"]:::model
        DurationComp["Duration"]:::model
        PauseComp["Pause"]:::model
        KeyComp["Key"]:::model
    end

    %% Data & External Layer (Red)
    subgraph "Data & External"
        direction TB
        CSVFile["map.csv"]:::external
        VPText["VirtualPiano Text Inputs"]:::external
        JavaSound["Java Sound API"]:::external
        GUIAssets["GUI Assets"]:::external
        BuildArtifact["PianoPlayer.jar"]:::external
    end

    %% Relationships
    MainWindow --> |"startApplication()"| ReaderComp
    ReaderComp --> |"loadMapping"| CSVFile
    ReaderComp --> |"parseComposition"| VPText
    ReaderComp --> |"build Composition"| CompositionComp

    CompositionComp --> |"data"| NoteView
    CompositionComp --> |"data"| Piano

    ControlBoard --> |"playEvent"| PlayerComp
    ControlBoard --> |"recordEvent"| RecorderComp

    PlayerComp --> |"playSymbols"| NotePlayerComp
    NotePlayerComp --> |"send MIDI"| JavaSound

    RecorderComp --> |"capture"| CompositionComp

    SaveDialog --> |"export TXT/MIDI"| CompositionComp
    SaveDialog --> |"write"| BuildArtifact

    MainWindow --> |"openAbout()"| AboutDialog
    MainWindow --> |"openSave()"| SaveDialog

    GUIAssets --> |"loadIcons"| ControlBoard

    %% Click Events
    click MainWindow "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Main.java"
    click ControlBoard "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/ControlBoard.java"
    click Piano "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Piano.java"
    click WhiteKey "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/WhiteKey.java"
    click BlackKey "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/BlackKey.java"
    click NoteView "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/NoteView.java"
    click AboutDialog "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/About.java"
    click SaveDialog "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/SaveDialog.java"
    click ReaderComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Reader.java"
    click PlayerComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Player.java"
    click NotePlayerComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/NotePlayer.java"
    click RecorderComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Recorder.java"
    click CompositionComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Composition.java"
    click MusicSymbolComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/MusicSymbol.java"
    click NoteComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Note.java"
    click DurationComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Duration.java"
    click PauseComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Pause.java"
    click KeyComp "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/src/pianosystem/Key.java"
    click CSVFile "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/data/map.csv"
    click VPText "https://github.com/zivkovicmilos/pianoplayer/tree/master/PianoPlayer/data/input/"
    click GUIAssets "https://github.com/zivkovicmilos/pianoplayer/tree/master/PianoPlayer/resources/imgs"
    click BuildArtifact "https://github.com/zivkovicmilos/pianoplayer/blob/master/PianoPlayer/out/artifacts/PianoPlayer_jar/PianoPlayer.jar"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef controller fill:#FFF4C1,stroke:#D4A72C,color:#735C0F;
    classDef model fill:#E2F0D9,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#FDECEA,stroke:#C62828,color:#C62828;
```
