| --- |
| license: agpl-3.0 |
| tags: |
| - music |
| - piano-fingering |
| - reinforcement-learning |
| - hidden-markov-model |
| --- |
| |
| # Chirality — trained piano-fingering models |
|
|
| Model artifacts for [vibetuned/chirality](https://github.com/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 |
|
|
| ```bash |
| 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](https://beam.kisarazu.ac.jp/research/PianoFingeringDataset/) |
| (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. |
|
|
