Try it live | GitHub

A web-based sight reading practice app for piano. Generates infinite procedural exercises with a structured curriculum that progresses from simple whole notes to complex rhythms across multiple keys.

• Structured Curriculum: 23 levels progressing through C major fundamentals, advanced rhythms, then new keys (G, F, D, Bb, etc.)
• Interleaved Hand Practice: Each concept is practiced RH → LH → Both hands before advancing
• MIDI Input: Connect your MIDI keyboard for real-time note detection
  • Correct notes highlight in teal
  • Wrong notes highlight in red
  • Forgiving timing (early notes accepted)
• Metronome: Count-off with 4-3-2-1 display, 16th note subdivisions
• Grand Staff: Clean notation with treble and bass clefs
• Progress Tracking: Mastery system requires consistent correct play before advancing
• Tempo Progression: Start slow (30 BPM), increase as you master each level

Each new key follows the same pattern (RH whole → LH whole → RH varied → Both):

• 11a-d: G major (1 sharp)
• 12a-d: F major (1 flat)
• 13a-d: D major (2 sharps)
• And so on through the circle of fifths...

• Tempo: Set BPM (starts at 30 for beginners)
• Metronome: Toggle on/off, adjust volume
• Level +/-: Manually adjust difficulty
• Options: Access level jump, key override, and fingering settings
• Start/Stop: Begin or end practice session

• Vite - Build tool
• TypeScript - Type safety
• Verovio - Music notation rendering (MusicXML → SVG)
• Tone.js - Web audio (metronome, sounds)
• Playwright - E2E testing
• Vitest - Unit testing
• Web MIDI API - MIDI keyboard input

# Install dependencies
npm install

# Start dev server
npm run dev

# Run unit tests
npm test

# Run E2E tests
npx playwright test

# Build for production
npm run build

# Deploy to GitHub Pages
npm run deploy

src/
├── core/             # Shared types, events, utilities
├── curriculum/       # Lessons and progress tracking
│   └── lessons/      # Lesson implementations
├── input/            # MIDI and performance tracking
├── music/            # Music generation and representation
│   ├── generators/   # Melody, pattern, scale generation
│   ├── sources/      # MusicSource implementations
│   └── xml/          # MusicXML building
├── playback/         # Audio playback engine
├── rendering/        # Visual rendering (Verovio)
├── main.ts           # App entry, UI, playback scheduling
├── musicGenerator.ts # Procedural music generation, curriculum
├── scheduler.ts      # Timing utilities for playback
├── fingeringEngine.ts# Piano fingering suggestions
└── __tests__/        # Unit tests

Key data flow:

1. musicGenerator creates NoteData[] for each hand
2. buildTimingEvents() extracts timing from note data
3. scheduleMusic() schedules playback via Tone.js
4. visualGroups maps SVG elements for highlighting

See CONTRIBUTING.md for guidelines.

LGPL-3.0 - See LICENSE for details.

Uses Verovio (LGPL-3.0).