# marcomusy/pianoplayer architecture

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

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

## Overview

##### Main Components
- User Interface Layer:
- CLI Interface: the main “pianoplayer” executable and accompanying batch file (pianoplayer.bat) to trigger the process.
- GUI Interface: triggered when no command-line arguments are given; supports score import, triggering fingering computation, and activating 3D view (via vedo).
- Input/Score Handling:
- ScoreReader (pianoplayer/scorereader.py): Reads and parses MusicXML, MIDI, or other supported score formats.
- Scores Directory: Contains various test scores and examples being used by the application.
- Core Fingering Engine:
- Core Algorithm (pianoplayer/core.py): Implements the dynamic programming technique optimizing finger transitions.
- Hand Model (pianoplayer/hand.py): Represents hand geometry and constraints (including parameters like hand size and beam numbers).
- Parameter/Utility Functions (pianoplayer/utils.py): General helper functions and parameter parsing.
- Output/Presentation Components:
- Virtual Keyboard / 3D Renderer (pianoplayer/vkeyboard.py): Handles the 3D visualization of the fingering annotations (integrated with vedo).
- Wave/Sound Generator (pianoplayer/wavegenerator.py): Responsible for audio output generation during 3D demonstrations.
- Output File Generation: Writing annotated MusicXML files (output.xml) that can be rendered by external software like MuseScore.
- External Integrations:
- External Tools: MuseScore for visualizing MusicXML; simpleaudio for sound; music21 for score processing (when needed); vedo for 3D rendering.

##### Relationships and Data Flow
- User Input (via CLI/GUI) → triggers file selection and passes score file path.
- ScoreReader module ingests and parses the score file → data is forwarded to Core Algorithm.
- Core Algorithm (with support from Hand and Utils modules) processes the note sequences and determines optimal fingerings.
- Processed data is then sent to:
- The Output generator (which writes the MusicXML file for MuseScore visualization).
- The Visualization module (Virtual Keyboard and 3D renderer via vedo) to display the annotated score.
- The Audio engine (WaveGenerator) if sound playback is enabled.
- Command-line options (like hand size or beam numbers) configure the internal behavior of the Core Algorithm.

##### Architectural Patterns and Design Principles
- Modularity: The project is segmented into distinct modules that handle score input, processing (fingering engine), visualization, and audio output.
- Separation of Concerns: Clear boundaries exist between the UI (CLI/GUI), core computation, and output generation.
- Dynamic Processing: The algorithm dynamically adapts its combinatorial search depth based on input score characteristics.
- External Dependency Integration: The system leverages external libraries and software (e.g., music21, simpleaudio, musescore, vedo) for specific tasks.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["CLI Executable"]:::ui
        UI2["Batch File"]:::ui
    end

    %% Score Handling
    subgraph "Score Handling"
        SD["Scores Directory"]:::input
        SR["ScoreReader"]:::input
    end

    %% Core Fingering Engine
    subgraph "Core Fingering Engine"
        CA["Core Algorithm"]:::core
        HM["Hand Model"]:::core
        UT["Utils & Parameter Parsing"]:::core
    end

    %% Output & Presentation Components
    subgraph "Output & Presentation"
        OMW["Output File Generation"]:::output
        V["3D Visualizer (Virtual Keyboard)"]:::output
        WG["Wave/Sound Generator"]:::output
    end

    %% External Integrations
    subgraph "External Integrations"
        M["MuseScore"]:::external
        VED["vedo"]:::external
        M21["music21"]:::external
        SA["simpleaudio"]:::external
    end

    %% Connections from User Interface to Score Handling
    UI1 -->|"provides file path"| SR
    UI2 -->|"provides file path"| SR
    SD -->|"contains score files"| SR

    %% ScoreReader interactions
    SR -->|"parsed score data"| CA
    SR -->|"score processing"| M21

    %% Core Fingering Engine interactions
    CA -->|"fingering data\n(annotated XML)"| OMW
    CA -->|"fingering data\n(3D instructions)"| V
    CA -->|"fingering data\n(audio instructions)"| WG
    HM --> CA
    UT --> CA

    %% Output & Presentation interactions with External Systems
    OMW -->|"opens in"| M
    V -->|"renders using"| VED
    WG -->|"outputs via"| SA

    %% Styles and Classes
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef input fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef core fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef output fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click UI1 "https://github.com/marcomusy/pianoplayer/tree/master/bin/pianoplayer"
    click UI2 "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer.bat"
    click SR "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/scorereader.py"
    click SD "https://github.com/marcomusy/pianoplayer/tree/master/scores"
    click CA "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/core.py"
    click HM "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/hand.py"
    click UT "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/utils.py"
    click V "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/vkeyboard.py"
    click WG "https://github.com/marcomusy/pianoplayer/blob/master/pianoplayer/wavegenerator.py"
```
