---
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.