Chirality — trained piano-fingering models
Model artifacts for vibetuned/chirality
(chirality on PyPI), a piano-fingering pipeline combining
ergonomic rule sets, statistical models, and reinforcement learning.
Contents
| Path | What | Human match (M_gen) |
|---|---|---|
weights/parncutt.json |
Path-difference learned Parncutt rule weights (Radisavljevic & Driessen 2004, trained on PIG) | 65.4 — best non-human system |
hmm/param_FHMM{1,2,3}.txt |
Nakamura et al. (2020) fingering HMMs, orders 1–3, trained on the PIG miscellaneous subset | 61.6 / 64.3 / 64.4 |
ppo/conv_jacobs.pt |
PPO conv policy, jacobs reward | 44.8 (right hand) |
ppo/decoder_hmm_nll.pt |
PPO decoder policy, HMM-NLL reward | 43.2 (right hand) |
ppo/transformer_hmm_nll.pt |
PPO transformer policy, HMM-NLL reward | 42.2 (right hand) |
ppo/simple_hmm_nll.pt |
PPO MLP policy, HMM-NLL reward | 39.9 (right hand) |
ppo/conv_mixed_hmm.pt |
PPO conv policy, mixed rules+HMM reward | 39.5 (right hand) |
Human inter-annotator agreement on the same benchmark is 71.4.
Evaluation protocol and full tables: docs/experiments_summary.md in
the code repository.
Usage
pip install chirality
chirality fetch-models # downloads this repo's models into ./data
chirality annotate --input score.mei --output ./annotated --weights --both
chirality annotate --input score.mei --output ./annotated --hmm --order 2
chirality fetch-models --ppo also pulls the PPO checkpoints.
PPO checkpoints load with chirality test --checkpoint ppo/<name>.pt --policy <arch> or chirality annotate --model ....
Provenance and licensing
Code is AGPL-3.0-or-later. The HMM parameters and learned rule weights are statistics estimated from the PIG dataset (Nakamura, Saito & Yoshii 2020), which is available for research and non-profit use — treat these artifacts under the same terms. The PPO checkpoints were trained purely on generated scores (scales, chords, arpeggios) and carry no PIG data.