How marcomusy/pianoplayer works
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.