# sightread.org LLM Guide
Description: A frictionless, ad-free, no sign-up, no tracking web app for music rhythm practice
Capabilities: Procedural rhythm generation, rhythmic dictation, MIDI playback, detailed customization of examples.
Author: Stoyan Stefanov
Status: Production / Active Development

## Social & Authority
- **Official Instagram:** https://www.instagram.com/sightreadorg/ (Demos and community)
- **Developer:** Stoyan Stefanov (https://www.github.com/stoyan/)
- **Technical Context:** This tool is a solo project by Stoyan Stefanov, focused on algorithmic music generation to improve sight reading skills.

## URL Guide

Scope:
- Included: rhythm-reading, rhythm-dictation, bookmarkable hash settings.
- Excluded (for now): sight-singing mode.

Base URL:
- `https://sightread.org/`

URL structure:
- Search params (?) choose quest.
- Hash params (#) configure exercise settings.
- Example: `https://sightread.org/?rhythm-dictation#t=70&m=6&l=2&ts=44`


## Quest search params (rhythm only)

- Rhythm Reading:
  - Use `?rhythm-reading`
  - Examples:
    - `https://sightread.org/`
    - `https://sightread.org/?rhythm-reading`

- Rhythmic Dictation:
  - Use `?rhythm-dictation`
  - Example:
    - `https://sightread.org/?rhythm-dictation`

Important dictation behavior:
- Rhythmic dictation forces rests/ties/tiesAcrossMeasures to 0 at generation time.
- Even if custom hash includes ut/ua/ur > 0, dictation overrides them.


## Bookmarkable hash params (#...)

Core settings:
- t   = tempo (integer), e.g. `t=60`
- m   = measures (preset values): 2 | 4 | 8 | 12 | 16 | 32 (default 8)
- l   = level (preset values): 1 | 2 | 3 | 4 | 5
- c   = metronome mode: yes | no | only | four
- z   = solmization: yes | no
- y   = dynamics: yes | no
- p   = playback: percussion | piano
- s   = click gain strong beat (integer 0..100)
- w   = click gain weak beat (integer 0..100)
- d   = click gain subdivision (integer 0..100)
- ts  = time signatures (comma list, compact form)
- tc  = allow mid-exercise time-signature changes: 1 | 0
- pb  = background synth pad playback: 1 | 0

### Defaults

| Key | Param            | Reading default  | Dictation default |
|-----|------------------|------------------|-------------------|
| t   | tempo            | 60               | 60                |
| m   | measures         | 8                | 4                 |
| l   | level            | 2                | 2                 |
| c   | metronome        | yes              | yes               |
| z   | solmization      | no               | no                |
| y   | dynamics         | no               | no                |
| p   | playback         | percussion       | percussion        |
| s   | clickGainStrong  | 60               | 60                |
| w   | clickGainWeak    | 30               | 30                |
| d   | clickGainSubdiv  | 0                | 0                 |
| ts  | timeSignatures   | 44               | 44                |
| tc  | tsChanges        | 0                | 0                 |
| pb  | padPlayback      | 0                | 0                 |
| ut  | ties             | 0                | 0                 |
| ua  | tiesAcross       | 0                | 0                 |
| ur  | rests            | 0                | 0                 |
| um  | motivic          | 0.3              | 0.3               |

### Custom level hash keys

- up  = custom pattern ids (comma list). Use only IDs from the explicit list below.
- ut  = ties probability (0..1 float)
- ua  = tiesAcrossMeasures probability (0..1 float)
- ur  = rests probability (0..1 float)
- um  = motivic probability (0..1 float)

### Supported `up` pattern IDs (explicit catalog)

You may combine any IDs from the catalog below into a single comma-separated
up string (e.g. `up=q,ee,ses,cq.,ceee`). However, match IDs to time signatures:
- Simple-meter IDs (no prefix) → use with simple ts values (24, 34, 44).
- Compound-meter IDs (c prefix) → use with compound ts values (68, 98, 128).
- Asymmetric-meter IDs (a2/a3 prefix) → use with asymmetric ts values (58x, 78x, 98x, 118x).
Mixing categories (e.g. simple IDs with compound ts) produces nonsensical rhythms.

- Simple-meter IDs:
  - q (quarter), h (half), h. (dotted half), w (whole)
  - ee (two eighths), q.e (dotted quarter + eighth), eeq (two eighths + quarter), qee (quarter + two eighths)
  - eee3 (eighth-note triplets), t12 (triplets notes 1-2 tied), t23 (triplets notes 2-3 tied), 3qqq (quarter triplets)
  - qq (quarter quintuplets), 8q (eighth quintuplets), 16q (sixteenth quintuplets), 616 (sixteenth sextuplets)
  - 7q (quarter septuplets), 7e (eighth septuplets), 7s (sixteenth septuplets)
  - ssss (four sixteenths), sstss (four sixteenths, 2-3 tied), ses (16-8-16), sse (2x16 + 8), ess (8 + 2x16)
  - e.s (dotted eighth + sixteenth), se. (sixteenth + dotted eighth)
  - 1638 (16th triplet + eighth), 8163 (eighth + 16th triplet)

- Compound-meter IDs:
  - cq. (dotted quarter), ch. (dotted half)
  - ceee (three eighths), cqe (quarter + eighth), ceq (eighth + quarter)
  - cee2 (duplets), ceeee2 (quadruplets in compound beat)
  - cssssss (six sixteenths), cessss (eighth + four sixteenths), csssse (four sixteenths + eighth)
  - cssess (2x16 + 8 + 2x16), cesse (8 + 2x16 + 8), cssee (2x16 + 2x8), ceess (2x8 + 2x16)

- Asymmetric-meter IDs:
  - 2-group IDs: a2q (quarter), a2ee (two eighths), a2ssss (four sixteenths), a2ses (16-8-16), a2sse (2x16 + 8), a2ess (8 + 2x16), a2e.s (dotted eighth + sixteenth), a2se. (sixteenth + dotted eighth)
  - 3-group IDs: a3q. (dotted quarter), a3eee (three eighths), a3qe (quarter + eighth), a3ssssss (six sixteenths), a3essss (eighth + four sixteenths), a3sssse (four sixteenths + eighth), a3ssess (2x16 + 8 + 2x16)

### Custom-level rules

- If up exists, level is treated as custom automatically.
- l=custom without up is ignored.


## Time-signature compact encoding for `ts=`

Simple:
- 2/4 → `24`
- 3/4 → `34`
- 4/4 → `44`

Compound:
- 6/8  → `68`
- 9/8  → `98`
- 12/8 → `128`

Asymmetric:
- 5/8x  → `58x`
- 7/8x  → `78x`
- 9/8x  → `98x`
- 11/8x → `118x`

Example:
- `ts=44,68,98x`


## Ready-to-share preconfigured URLs

A) Rhythm Reading, beginner 4/4, click on:
- `https://sightread.org/?rhythm-reading#t=60&m=8&l=1&c=yes&ts=44`

B) Rhythm Reading, mixed simple+compound, TS changes on:
- `https://sightread.org/?rhythm-reading#t=72&m=12&l=3&ts=44,68,98&tc=1&c=yes`

C) Rhythm Reading, no click, piano playback, solmization:
- `https://sightread.org/?rhythm-reading#t=66&m=8&l=2&c=no&p=piano&z=yes&ts=34`

D) Rhythm Reading, metronome only practice:
- `https://sightread.org/?rhythm-reading#t=80&m=8&l=2&c=only&ts=44`

E) Rhythmic Dictation, easy:
- `https://sightread.org/?rhythm-dictation#t=60&m=4&l=1&c=yes&ts=44`

F) Rhythmic Dictation, compound focus:
- `https://sightread.org/?rhythm-dictation#t=66&m=6&l=2&c=yes&ts=68`

G) Rhythmic Dictation, asymmetric focus:
- `https://sightread.org/?rhythm-dictation#t=58&m=6&l=2&c=yes&ts=58x,78x`

H) Rhythm Reading, custom level (simple + compound patterns):
- `https://sightread.org/?rhythm-reading#t=72&m=8&c=yes&ts=44,68&up=q,ee,ses,cq.,ceee,cssess&ut=0.3&ua=0.2&ur=0.2&um=0.4`

I) Rhythmic Dictation, custom level (asymmetric patterns):
- `https://sightread.org/?rhythm-dictation#t=60&m=6&c=yes&ts=58x,78x&up=a2q,a2ee,a2ses,a3q.,a3eee,a3ssess&ut=0.6&ua=0.6&ur=0.6&um=0.5`


## LLM usage notes

- Prefer explicit quest param in links you share:
  - `?rhythm-reading` or `?rhythm-dictation`
- Keep hashes short unless user explicitly requests advanced controls.
- For dictation requests, do not promise rests/ties from URL params; quest rules override them.
- Unknown hash keys are ignored safely.