PianoPlayer

PianoPlayer automatically determines how to assign hands to parts or staves. You can use --auto-routing (default) or --manual-routing to override this behavior.

Routing Logic:

• 2-part piano scores: Hands are selected by -rpart and -lpart.
• 1-part, 2-staff piano scores: Hands are selected by staff (RH -> staff 1, LH -> staff 2).
• Manual Override: Use --manual-routing combined with --rstaff and --lstaff to explicitly define staff numbers for the right and left hands.

Run PianoPlayer from the command line to generate fingerings for a score file.

Example command: pianoplayer scores/bach_invention4.xml -n 10 -r -v -z -m This command annotates the first 10 measures for the right hand, enables 3D playback, disables sound, and opens the result in MuseScore.

Default Outputs:

• MusicXML/MuseScore inputs: Defaults to output.xml.
• MIDI/PIG inputs: Defaults to annotated tabular output in output.txt.

Install the core package using pip:

pip install pianoplayer

You can also install optional extras for specific functionality:

• 3D rendering with vedo: pip install "pianoplayer[visual]"
• MIDI input support: pip install "pianoplayer[midi]"
• Enable playback: pip install "pianoplayer[sound]"
• All optional extras: pip install "pianoplayer[all]"

To create a standalone executable (without 3D visualization) using PyInstaller, install the build extra and run the provided script:

pip install "pianoplayer[build]"
python scripts/build_standalone.py

Output locations:

• Linux/macOS: dist/pianoplayer
• Windows: dist/pianoplayer.exe

To run the PianoPlayer Web API on your local machine, install the package with the [web] extra and use uvicorn to start the server.

Supported score file formats for upload include: .xml, .mxl, .mid, .midi, .mscz, .mscx, and .txt.

pip install "pianoplayer[web]"
uvicorn webapi.app:app --host 127.0.0.1 --port 8000

To launch the graphical user interface, run pianoplayer without any filename arguments.

GUI Workflow:

1. Import Score: Click to load valid formats (MusicXML/MXL, MuseScore, MIDI, PIG).
2. Generate: Click GENERATE to process the score. Output is saved to output.xml (scores) or output.txt (MIDI/PIG).
3. Visualize: Click Musescore to view the annotated score (Linux/macOS only).
4. Advanced Settings: Use the Advanced menu to:
   • Toggle Auto hand routing.
   • Set manual part/staff routing.
   • Enable Colorize hands or Colorize by cost.
5. Quit: Press Quit, q, or Ctrl+W to exit.

The annotate() function executes a multi-stage pipeline:

1. Parsing: Loads the input file (MusicXML, MIDI, etc.) and resolves routing (which part/staff belongs to which hand).
2. Anchor Detection: Scans the input for existing fingering data. If found, these notes are treated as 'anchors' and preserved during optimization.
3. Hand Generation: Creates Hand objects for the right and left hands. The solver optimizes fingering based on the specified hand_size and depth.
4. Output Writing:
   • For MusicXML: Annotates the score with fingering and color information.
   • For PIG/MIDI: Writes a tab-separated text file containing note events.
5. Optional 3D Playback: If with_vedo is enabled, launches a 3D virtual keyboard visualization.

The VirtualKeyboard.play() method implements a step-by-step playback loop.

The Lifecycle:

1. Initialization: The keyboard scene, hands (left/right), and decorative elements are built.
2. The Loop: The method enters a while loop that increments absolute time t by dt.
3. Hand Movement: For each hand, the system:
   • Releases notes: If a note's duration has elapsed, the finger and key are visually 'released' (moved back to neutral position).
   • Attacks notes: If a note's start time is reached, the finger moves to the correct position and the key is pressed.
4. User Interaction: The loop blocks at each note attack using _wait_for_advance_key(). The user must press Space to proceed to the next note or Esc/q to abort.
5. Audio: If playsounds is True and an audio backend is available, play_sound() is called during note attacks.

PianoPlayer can be run from the command line to annotate music files (MusicXML, MIDI, etc.) with optimized fingerings. You can provide a filename as a positional argument, or launch the Tkinter GUI by using the --gui flag or by running the command without any arguments.

Supported Input Formats:

• MusicXML (.xml, .mxl)
• MuseScore (.mscz, .mscx)
• MIDI (.mid, .midi)
• PIG (.txt)

Basic Usage:

# Process a file with default settings
pianoplayer my_score.mxl

# Launch the GUI
pianoplayer --gui

# Process a file and save to a specific output name
pianoplayer my_score.mid -o annotated_output.mid

Use the GET /health endpoint to verify that the PianoPlayer Web API server is running correctly. It returns a simple JSON status object.

// Response from GET /health
{
  "status": "ok"
}