# chickend233/midikey-player architecture

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

- Interactive diagram: https://gitdiagram.com/chickend233/midikey-player
- Repository: https://github.com/chickend233/midikey-player

## Overview

MidiKeyPlayer is a Windows desktop MIDI-to-keyboard-and-mouse player with score editing, live MIDI input, playlist playback, and optional synchronization. The main workflow is: open a MIDI file, choose tracks and a keymap, optionally edit the score, then schedule mapped notes and send input to the foreground application. The graph also shows preview/export, playlist persistence, settings, updates, and sync. Several relationships come from README descriptions or the SOURCE INDEX; unsampled synchronization wiring is left unverified.

Main entry points: [`MidiKeyPlayer/MainWindow.axaml.cs`](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/MainWindow.axaml.cs) (Main Window), [`MidiKeyPlayer/PlaylistWindow.axaml.cs`](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/PlaylistWindow.axaml.cs) (Playlist Window), [`MidiKeyPlayer/Engine/PlaybackEngine.cs`](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/PlaybackEngine.cs) (Playback Engine), [`MidiKeyPlayer/Engine/SyncSession.cs`](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncSession.cs) (Sync Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop App"]
  node_main["Main Window"]
  node_playlistui["Playlist Window"]
  node_overlay["Playback Overlay"]
  node_settingsui["Settings UI"]
end

subgraph group_midi["MIDI and Editing"]
  node_midiinput["MIDI Loader<br/>[MidiLoader.cs]"]
  node_trackroles["Track Roles<br/>[GmInstrument.cs]"]
  node_roll["Piano Roll<br/>[PianoRoll.cs]"]
  node_score["Score Editing<br/>[ScoreEditor.cs]"]
  node_midiexport["MIDI Export<br/>[MidiExporter.cs]"]
  node_preview["MIDI Preview<br/>[MidiPreview.cs]"]
end

subgraph group_playback["Playback and Input"]
  node_keymap["Keymap Profiles<br/>[KeymapProfile.cs]"]
  node_mapper["Note Mapper<br/>[NoteMapper.cs]"]
  node_engine["Playback Engine<br/>[PlaybackEngine.cs]"]
  node_timing["Input Timing<br/>[InputTiming.cs]"]
  node_sender["Input Sender<br/>[InputSender.cs]"]
  node_live["Live Playback<br/>[LivePlayback.cs]"]
  node_midiin["MIDI Device Input"]
  node_hotkeys["Global Hotkeys<br/>[GlobalHotkeys.cs]"]
end

subgraph group_state["State and Sync"]
  node_playlist["Playlist Model<br/>[PlaylistModel.cs]"]
  node_store[("Playlist Store<br/>[PlaylistStore.cs]")]
  node_config[("App Configuration<br/>[AppConfig.cs]")]
  node_updater["Auto Update<br/>[AutoUpdate.cs]"]
  node_syncsession["Sync Session<br/>[SyncSession.cs]"]
  node_syncrelay["Sync Relay<br/>[SyncRelay.cs]"]
  node_syncclock["Sync Clock<br/>[SyncClock.cs]"]
end

node_user(("User"))
node_relayservice["Relay Service<br/>[index.js]"]
node_target(("Foreground App"))

node_user -->|"opens and controls"| node_main
node_main -->|"loads MIDI"| node_midiinput
node_midiinput -->|"identifies tracks"| node_trackroles
node_main -->|"edits score"| node_roll
node_roll -.->|"edits notes"| node_score
node_main -->|"exports score"| node_midiexport
node_main -->|"previews MIDI"| node_preview
node_main -->|"selects mapping"| node_keymap
node_main -->|"maps notes"| node_mapper
node_main -->|"starts playback"| node_engine
node_engine -->|"schedules timing"| node_timing
node_engine -->|"sends input"| node_sender
node_sender -->|"injects key events"| node_target
node_main -->|"configures live input"| node_midiin
node_midiin -->|"delivers note events"| node_live
node_live -->|"sends mapped input"| node_sender
node_main -->|"registers controls"| node_hotkeys
node_main -->|"opens manager"| node_playlistui
node_playlistui -->|"edits entries"| node_playlist
node_playlistui -->|"reads and writes"| node_store
node_main -->|"loads playlists"| node_store
node_main -->|"shows playback status"| node_overlay
node_main -->|"opens settings"| node_settingsui
node_main -->|"loads and saves"| node_config
node_settingsui -->|"configures profiles"| node_keymap
node_main -->|"checks updates"| node_updater
node_main -.->|"coordinates sync"| node_syncsession
node_syncsession -->|"uses relay"| node_syncrelay
node_syncsession -->|"uses clock"| node_syncclock
node_syncrelay -.->|"may communicate"| node_relayservice

click node_main "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/MainWindow.axaml.cs"
click node_playlistui "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/PlaylistWindow.axaml.cs"
click node_overlay "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/OverlayWindow.axaml.cs"
click node_settingsui "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/SettingsWindow.Keymap.cs"
click node_midiinput "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/MidiLoader.cs"
click node_trackroles "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/GmInstrument.cs"
click node_roll "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Controls/PianoRoll.cs"
click node_score "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/ScoreEditor.cs"
click node_midiexport "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/MidiExporter.cs"
click node_preview "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/MidiPreview.cs"
click node_keymap "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/KeymapProfile.cs"
click node_mapper "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/NoteMapper.cs"
click node_engine "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/PlaybackEngine.cs"
click node_timing "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/InputTiming.cs"
click node_sender "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Input/InputSender.cs"
click node_live "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/LivePlayback.cs"
click node_midiin "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/MidiInputService.cs"
click node_hotkeys "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Input/GlobalHotkeys.cs"
click node_playlist "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/PlaylistModel.cs"
click node_store "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Persist/PlaylistStore.cs"
click node_config "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Persist/AppConfig.cs"
click node_updater "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/AutoUpdate.cs"
click node_syncsession "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncSession.cs"
click node_syncrelay "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncRelay.cs"
click node_syncclock "https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncClock.cs"
click node_relayservice "https://github.com/chickend233/midikey-player/blob/main/cloudflare/src/index.js"

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_main,node_playlistui,node_overlay,node_settingsui,node_user toneBlue
class node_midiinput,node_trackroles,node_roll,node_score,node_midiexport,node_preview toneAmber
class node_keymap,node_mapper,node_engine,node_timing,node_sender,node_live,node_midiin,node_hotkeys toneMint
class node_playlist,node_store,node_config,node_updater,node_syncsession,node_syncrelay,node_syncclock toneRose
class node_relayservice toneTeal
class node_target toneIndigo
```

## Components

### Desktop App

- [Main Window](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/MainWindow.axaml.cs): `MidiKeyPlayer/MainWindow.axaml.cs`
- [Playlist Window](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/PlaylistWindow.axaml.cs): `MidiKeyPlayer/PlaylistWindow.axaml.cs`
- [Playback Overlay](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/OverlayWindow.axaml.cs): `MidiKeyPlayer/OverlayWindow.axaml.cs`
- [Settings UI](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/SettingsWindow.Keymap.cs): `MidiKeyPlayer/SettingsWindow.Keymap.cs`

### MIDI and Editing

- [MIDI Loader](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/MidiLoader.cs): `MidiKeyPlayer/Midi/MidiLoader.cs`
- [Track Roles](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/GmInstrument.cs): `MidiKeyPlayer/Midi/GmInstrument.cs`
- [Piano Roll](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Controls/PianoRoll.cs): `MidiKeyPlayer/Controls/PianoRoll.cs`
- [Score Editing](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/ScoreEditor.cs): `MidiKeyPlayer/Engine/ScoreEditor.cs`
- [MIDI Export](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/MidiExporter.cs): `MidiKeyPlayer/Engine/MidiExporter.cs`
- [MIDI Preview](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/MidiPreview.cs): `MidiKeyPlayer/Engine/MidiPreview.cs`

### Playback and Input

- [Keymap Profiles](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/KeymapProfile.cs): `MidiKeyPlayer/Engine/KeymapProfile.cs`
- [Note Mapper](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/NoteMapper.cs): `MidiKeyPlayer/Engine/NoteMapper.cs`
- [Playback Engine](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/PlaybackEngine.cs): `MidiKeyPlayer/Engine/PlaybackEngine.cs`
- [Input Timing](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/InputTiming.cs): `MidiKeyPlayer/Engine/InputTiming.cs`
- [Input Sender](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Input/InputSender.cs): `MidiKeyPlayer/Input/InputSender.cs`
- [Live Playback](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/LivePlayback.cs): `MidiKeyPlayer/Engine/LivePlayback.cs`
- [MIDI Device Input](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Midi/MidiInputService.cs): `MidiKeyPlayer/Midi/MidiInputService.cs`
- [Global Hotkeys](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Input/GlobalHotkeys.cs): `MidiKeyPlayer/Input/GlobalHotkeys.cs`

### State and Sync

- [Playlist Model](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/PlaylistModel.cs): `MidiKeyPlayer/Engine/PlaylistModel.cs`
- [Playlist Store](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Persist/PlaylistStore.cs): `MidiKeyPlayer/Persist/PlaylistStore.cs`
- [App Configuration](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Persist/AppConfig.cs): `MidiKeyPlayer/Persist/AppConfig.cs`
- [Auto Update](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/AutoUpdate.cs): `MidiKeyPlayer/Engine/AutoUpdate.cs`
- [Sync Session](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncSession.cs): `MidiKeyPlayer/Engine/SyncSession.cs`
- [Sync Relay](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncRelay.cs): `MidiKeyPlayer/Engine/SyncRelay.cs`
- [Sync Clock](https://github.com/chickend233/midikey-player/blob/main/MidiKeyPlayer/Engine/SyncClock.cs): `MidiKeyPlayer/Engine/SyncClock.cs`

### Other components

- **User**
- [Relay Service](https://github.com/chickend233/midikey-player/blob/main/cloudflare/src/index.js): `cloudflare/src/index.js`
- **Foreground App**

## Connections

- User → Main Window: opens and controls
- Main Window → MIDI Loader: loads MIDI (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- MIDI Loader → Track Roles: identifies tracks (evidence: `MidiKeyPlayer/Midi/MidiLoader.cs`)
- Main Window → Piano Roll: edits score (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Piano Roll → Score Editing: edits notes
- Main Window → MIDI Export: exports score (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → MIDI Preview: previews MIDI (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Keymap Profiles: selects mapping (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Note Mapper: maps notes (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Playback Engine: starts playback (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Playback Engine → Input Timing: schedules timing (evidence: `MidiKeyPlayer/Engine/PlaybackEngine.cs`)
- Playback Engine → Input Sender: sends input (evidence: `MidiKeyPlayer/Engine/PlaybackEngine.cs`)
- Input Sender → Foreground App: injects key events
- Main Window → MIDI Device Input: configures live input (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- MIDI Device Input → Live Playback: delivers note events (evidence: `MidiKeyPlayer/Engine/LivePlayback.cs`)
- Live Playback → Input Sender: sends mapped input (evidence: `MidiKeyPlayer/Engine/LivePlayback.cs`)
- Main Window → Global Hotkeys: registers controls (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Playlist Window: opens manager
- Playlist Window → Playlist Model: edits entries (evidence: `MidiKeyPlayer/PlaylistWindow.axaml.cs`)
- Playlist Window → Playlist Store: reads and writes (evidence: `MidiKeyPlayer/PlaylistWindow.axaml.cs`)
- Main Window → Playlist Store: loads playlists (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Playback Overlay: shows playback status
- Main Window → Settings UI: opens settings
- Main Window → App Configuration: loads and saves (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Settings UI → Keymap Profiles: configures profiles (evidence: `MidiKeyPlayer/SettingsWindow.Keymap.cs`)
- Main Window → Auto Update: checks updates (evidence: `MidiKeyPlayer/MainWindow.axaml.cs`)
- Main Window → Sync Session: coordinates sync
- Sync Session → Sync Relay: uses relay (evidence: `MidiKeyPlayer/Engine/SyncSession.cs`)
- Sync Session → Sync Clock: uses clock (evidence: `MidiKeyPlayer/Engine/SyncSession.cs`)
- Sync Relay → Relay Service: may communicate
