# Hand-Position Trellis dashboard

A single-page visualization of the optimizer in `../findOptimalHandPos.py`.
For each of the 61 example songs it shows every candidate hand position the
optimizer considered at each note, which one it kept and why, a piano roll
with audio, and a right-hand-only mode that simulates a failed left hand.

## Files

- `index.html`: the whole app (HTML, CSS and JavaScript). No build step and
  no dependencies other than Google Fonts.
- `data-manifest.json` and `data-part*.json`: the precomputed trace data for
  every song, both modes and both hands, split into chunks (see below).
  Generated by `../scripts/build_dashboard_data.py`. See
  `../docs/DEVELOPERS.md` to regenerate it after adding or editing a song.
- `songs_manifest.json`: a readable `{key, label}` list of every song,
  written by the same build script.

## Why the data is chunked

The full trace is about 20 MB, and some static hosts limit the size of a
single file. The dashboard always loads `data-manifest.json` (a list of chunk
files), fetches every chunk in parallel and merges them before rendering.
The build script packs songs into chunks below a fixed size, so the same code
works for any number of songs.

## Running it locally

`index.html` fetches its data when it loads, so it must be served over HTTP:

```
python3 -m http.server 8000
```

Then open `http://localhost:8000/`.

## Songs

61 songs: 6 traced from MusicXML scores and 55 generated to test specific
parts of the optimizer. Scale runs test the speed limit, arpeggios and broken
chords test the move penalty, black-key trills test the fingering penalty,
leap studies test how move and speed penalties scale with distance, and
repeated notes test zero-cost steps. See `songs_manifest.json` for the full
list and `../scripts/generate_new_songs.py` for what each song tests.