# dhnguyencs/digital-piano architecture

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

- Interactive diagram: https://gitdiagram.com/dhnguyencs/digital-piano
- Repository: https://github.com/dhnguyencs/digital-piano

## Overview

Digital-Piano is a desktop piano synthesizer that accepts live MIDI input and plays MIDI files with a visual keyboard. Its main workflow starts in `main.cpp`, which initializes audio and launches controller threads; the controller handles piano interaction and song playback, while the mapper translates notes into key and sound state. The README also documents playback-speed and seek controls. MIDI parsing and real-time MIDI I/O are distinct supporting capabilities. Source excerpts do not show every controller method, so some documented or strongly implied links are marked unverified.

Main entry points: [`main.cpp`](https://github.com/dhnguyencs/digital-piano/blob/main/main.cpp) (App launcher), [`MAPPER.h`](https://github.com/dhnguyencs/digital-piano/blob/main/MAPPER.h) (Note mapper), [`DigitalPiano.h`](https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h) (Song playback), [`src/MidiFile.cpp`](https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiFile.cpp) (MIDI file model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_player["App launcher<br/>[main.cpp]"]
  node_controller["Piano controller<br/>[DigitalPiano.h]"]
  node_globals["Window settings<br/>[GLOBALVARIABLES.h]"]
end

subgraph group_interaction["Piano Interaction"]
  node_keyboard_ui["Piano UI<br/>[DigitalPiano.h]"]
  node_pixel_engine["Pixel game engine"]
  node_key_layout["Key layout<br/>[Keys.h]"]
  node_mapper["Note mapper<br/>[MAPPER.h]"]
  node_vectors["Vector math<br/>[vectors.h]"]
end

subgraph group_midi["MIDI Processing"]
  node_midi_input["Live MIDI input<br/>[DigitalPiano.h]"]
  node_rtmidi["RtMidi interface<br/>[RtMidi.h]"]
  node_rtmidi_impl["RtMidi backend<br/>[RtMidi.cpp]"]
  node_song_playback["Song playback<br/>[DigitalPiano.h]"]
  node_midi_files["MIDI file model<br/>[MidiFile.cpp]"]
  node_midi_events["MIDI event lists<br/>[MidiEventList.cpp]"]
  node_midi_event["MIDI events<br/>[MidiEvent.cpp]"]
  node_midi_message["MIDI messages<br/>[MidiMessage.cpp]"]
  node_binasc["Binasc conversion<br/>[Binasc.cpp]"]
  node_options["Option parser<br/>[Options.cpp]"]
  node_midi_library["MIDI library"]
  node_midi_assets["Bundled MIDI songs"]
end

subgraph group_audio["Audio"]
  node_sf2["SoundFont<br/>[soundfile_3.sf2]"]
  node_synth["SoundFont synthesizer<br/>[tsf.h]"]
  node_audio_output["SDL audio output<br/>[minisdl_audio.h]"]
end

node_midi_device(("MIDI device"))
node_song_user(("Song selection"))

node_player -->|"launches threads"| node_controller
node_player -->|"constructs"| node_mapper
node_player -->|"constructs app"| node_keyboard_ui
node_player -->|"loads SoundFont"| node_synth
node_player -->|"opens output"| node_audio_output
node_player -->|"configures window"| node_globals
node_controller -->|"runs input thread"| node_midi_input
node_controller -->|"runs playback thread"| node_song_playback
node_controller -.->|"renders interface"| node_keyboard_ui
node_keyboard_ui -->|"extends engine"| node_pixel_engine
node_keyboard_ui -->|"updates key state"| node_mapper
node_mapper -->|"builds keyboard"| node_key_layout
node_key_layout -->|"uses geometry"| node_vectors
node_mapper -->|"uses geometry"| node_vectors
node_midi_device -.->|"sends notes"| node_midi_input
node_midi_input -->|"polls input"| node_rtmidi
node_rtmidi_impl -->|"implements API"| node_rtmidi
node_song_user -.->|"selects song"| node_song_playback
node_song_playback -.->|"reads MIDI"| node_midi_files
node_midi_assets -.->|"provides songs"| node_song_playback
node_midi_files -->|"uses declarations"| node_midi_library
node_midi_library -->|"stores tracks"| node_midi_events
node_midi_events -->|"contains events"| node_midi_event
node_midi_event -->|"uses message"| node_midi_message
node_midi_files -.->|"supports conversion"| node_binasc
node_midi_files -.->|"uses options"| node_options
node_song_playback -.->|"maps played notes"| node_mapper
node_mapper -->|"triggers notes"| node_synth
node_player -->|"renders samples"| node_synth
node_sf2 -.->|"supplies presets"| node_synth

click node_player "https://github.com/dhnguyencs/digital-piano/blob/main/main.cpp"
click node_controller "https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h"
click node_globals "https://github.com/dhnguyencs/digital-piano/blob/main/GLOBALVARIABLES.h"
click node_keyboard_ui "https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h"
click node_pixel_engine "https://github.com/dhnguyencs/digital-piano/blob/main/olcPixelGameEngineGL.h"
click node_key_layout "https://github.com/dhnguyencs/digital-piano/blob/main/Keys.h"
click node_mapper "https://github.com/dhnguyencs/digital-piano/blob/main/MAPPER.h"
click node_vectors "https://github.com/dhnguyencs/digital-piano/blob/main/vectors.h"
click node_midi_input "https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h"
click node_rtmidi "https://github.com/dhnguyencs/digital-piano/blob/main/RtMidi.h"
click node_rtmidi_impl "https://github.com/dhnguyencs/digital-piano/blob/main/RtMidi.cpp"
click node_song_playback "https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h"
click node_midi_files "https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiFile.cpp"
click node_midi_events "https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiEventList.cpp"
click node_midi_event "https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiEvent.cpp"
click node_midi_message "https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiMessage.cpp"
click node_binasc "https://github.com/dhnguyencs/digital-piano/blob/main/src/Binasc.cpp"
click node_options "https://github.com/dhnguyencs/digital-piano/blob/main/src/Options.cpp"
click node_midi_library "https://github.com/dhnguyencs/digital-piano/tree/main/include"
click node_sf2 "https://github.com/dhnguyencs/digital-piano/blob/main/soundfile_3.sf2"
click node_synth "https://github.com/dhnguyencs/digital-piano/blob/main/tsf.h"
click node_audio_output "https://github.com/dhnguyencs/digital-piano/blob/main/minisdl_audio.h"
click node_midi_assets "https://github.com/dhnguyencs/digital-piano/tree/main/MIDIFILES"

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_player,node_controller,node_globals toneBlue
class node_keyboard_ui,node_pixel_engine,node_key_layout,node_mapper,node_vectors toneAmber
class node_midi_input,node_rtmidi,node_rtmidi_impl,node_song_playback,node_midi_files,node_midi_events,node_midi_event,node_midi_message,node_binasc,node_options,node_midi_library,node_midi_assets toneMint
class node_sf2,node_synth,node_audio_output toneRose
class node_midi_device,node_song_user toneIndigo
```

## Components

### Application

- [App launcher](https://github.com/dhnguyencs/digital-piano/blob/main/main.cpp): `main.cpp`
- [Piano controller](https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h): `DigitalPiano.h`
- [Window settings](https://github.com/dhnguyencs/digital-piano/blob/main/GLOBALVARIABLES.h): `GLOBALVARIABLES.h`

### Piano Interaction

- [Piano UI](https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h): `DigitalPiano.h`
- [Pixel game engine](https://github.com/dhnguyencs/digital-piano/blob/main/olcPixelGameEngineGL.h): `olcPixelGameEngineGL.h`
- [Key layout](https://github.com/dhnguyencs/digital-piano/blob/main/Keys.h): `Keys.h`
- [Note mapper](https://github.com/dhnguyencs/digital-piano/blob/main/MAPPER.h): `MAPPER.h`
- [Vector math](https://github.com/dhnguyencs/digital-piano/blob/main/vectors.h): `vectors.h`

### MIDI Processing

- [Live MIDI input](https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h): `DigitalPiano.h`
- [RtMidi interface](https://github.com/dhnguyencs/digital-piano/blob/main/RtMidi.h): `RtMidi.h`
- [RtMidi backend](https://github.com/dhnguyencs/digital-piano/blob/main/RtMidi.cpp): `RtMidi.cpp`
- [Song playback](https://github.com/dhnguyencs/digital-piano/blob/main/DigitalPiano.h): `DigitalPiano.h`
- [MIDI file model](https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiFile.cpp): `src/MidiFile.cpp`
- [MIDI event lists](https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiEventList.cpp): `src/MidiEventList.cpp`
- [MIDI events](https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiEvent.cpp): `src/MidiEvent.cpp`
- [MIDI messages](https://github.com/dhnguyencs/digital-piano/blob/main/src/MidiMessage.cpp): `src/MidiMessage.cpp`
- [Binasc conversion](https://github.com/dhnguyencs/digital-piano/blob/main/src/Binasc.cpp): `src/Binasc.cpp`
- [Option parser](https://github.com/dhnguyencs/digital-piano/blob/main/src/Options.cpp): `src/Options.cpp`
- [MIDI library](https://github.com/dhnguyencs/digital-piano/tree/main/include): `include`
- [Bundled MIDI songs](https://github.com/dhnguyencs/digital-piano/tree/main/MIDIFILES): `MIDIFILES`

### Audio

- [SoundFont](https://github.com/dhnguyencs/digital-piano/blob/main/soundfile_3.sf2): `soundfile_3.sf2`
- [SoundFont synthesizer](https://github.com/dhnguyencs/digital-piano/blob/main/tsf.h): `tsf.h`
- [SDL audio output](https://github.com/dhnguyencs/digital-piano/blob/main/minisdl_audio.h): `minisdl_audio.h`

### Other components

- **MIDI device**
- **Song selection**

## Connections

- App launcher → Piano controller: launches threads (evidence: `main.cpp`)
- App launcher → Note mapper: constructs (evidence: `main.cpp`)
- App launcher → Piano UI: constructs app (evidence: `main.cpp`)
- App launcher → SoundFont synthesizer: loads SoundFont (evidence: `main.cpp`)
- App launcher → SDL audio output: opens output (evidence: `main.cpp`)
- App launcher → Window settings: configures window (evidence: `main.cpp`)
- Piano controller → Live MIDI input: runs input thread (evidence: `main.cpp`)
- Piano controller → Song playback: runs playback thread (evidence: `main.cpp`)
- Piano controller → Piano UI: renders interface (evidence: `DigitalPiano.h`)
- Piano UI → Pixel game engine: extends engine (evidence: `DigitalPiano.h`)
- Piano UI → Note mapper: updates key state (evidence: `DigitalPiano.h`)
- Note mapper → Key layout: builds keyboard (evidence: `MAPPER.h`)
- Key layout → Vector math: uses geometry (evidence: `Keys.h`)
- Note mapper → Vector math: uses geometry (evidence: `MAPPER.h`)
- MIDI device → Live MIDI input: sends notes
- Live MIDI input → RtMidi interface: polls input (evidence: `DigitalPiano.h`)
- RtMidi backend → RtMidi interface: implements API (evidence: `RtMidi.cpp`)
- Song selection → Song playback: selects song (evidence: `README.md`)
- Song playback → MIDI file model: reads MIDI (evidence: `README.md`)
- Bundled MIDI songs → Song playback: provides songs (evidence: `README.md`)
- MIDI file model → MIDI library: uses declarations (evidence: `include/MidiFile.h`)
- MIDI library → MIDI event lists: stores tracks (evidence: `include/MidiFile.h`)
- MIDI event lists → MIDI events: contains events
- MIDI events → MIDI messages: uses message
- MIDI file model → Binasc conversion: supports conversion (evidence: `src/MidiFile.cpp`)
- MIDI file model → Option parser: uses options
- Song playback → Note mapper: maps played notes (evidence: `DigitalPiano.h`)
- Note mapper → SoundFont synthesizer: triggers notes (evidence: `MAPPER.h`)
- App launcher → SoundFont synthesizer: renders samples (evidence: `main.cpp`)
- SoundFont → SoundFont synthesizer: supplies presets
