# Learn Piano

Interactive piano learning site with **two audiences**:

| Path | File | Idea |
|------|------|------|
| **Landing** | [`index.html`](index.html) | Choose Theory and Practice or Quest Mode |
| **Theory and Practice** | [`theory.html`](theory.html) / [`theory.md`](theory.md) | Keyboard, guided scales (fingering + hands), chords, metronome, 4-week plan |
| **Appendix · Training routines** | [`routines.html`](routines.html) / [`routines.md`](routines.md) | Guided workouts — Scale Forge, Circle of Fifths, Chord & Arp Bootcamp, Progression Drill (connect MIDI/mic) |
| **Ear training** | [/tools/ear-training.html](/tools/ear-training.html) | Shared Tools hub (not this room) |
| **Appendix · Drills** | [`drills.html`](drills.html) / [`drills.md`](drills.md) | Wake up your hands — five-finger, contrary motion, trills, thumb-under (interactive, with Play along) |
| **Appendix · Exercises** | [`exercises.html`](exercises.html) / [`exercises.md`](exercises.md) | Build technique — Hanon No. 1, scales, arpeggios, two-against-one hand syncing |
| **Appendix · Hanon (Part I)** | [`hanon.html`](hanon.html) / [`hanon.md`](hanon.md) | All 20 Part I exercises transcribed to notation — read & hear on a grand staff with play cursor and keyboard (data from Mutopia, CC BY-SA) |
| **Sight reading** | [`reading.html`](reading.html) / [`reading.md`](reading.md) | Progressive treble → bass → grand-staff note-naming drills; full Hanon score reader (all 60, PDF) |
| **Time signatures** | [`time-signatures.html`](time-signatures.html) / [`time-signatures.md`](time-signatures.md) | Western meter — 2/4, 3/4, 4/4, 6/8, odd groupings; feel it on the metronome |
| **Note values** | [`note-values.html`](note-values.html) / [`note-values.md`](note-values.md) | Whole, half, quarter, eighth, sixteenth — how they fill a bar; write and hear a rhythm |
| **Highway** | [`highway.html`](highway.html) / [`highway.md`](highway.md) | Falling-note game — Easy/Medium/Hard PD songs, Practice & Performance, MIDI import |
| **Appendix · Modes** | [`modes.html`](modes.html) / [`modes.md`](modes.md) | The seven diatonic modes — hear each, formulas, characteristic notes |
| **Appendix · Beyond scales** | [`beyond-scales.html`](beyond-scales.html) / [`beyond-scales.md`](beyond-scales.md) | Beyond the major scale — minor family, pentatonic/blues/symmetrical, melodic- & harmonic-minor modes |
| **Appendix · Circle of fifths** | [`circle-of-fifths.html`](circle-of-fifths.html) / [`circle-of-fifths.md`](circle-of-fifths.md) | Interactive wheel — key signatures, relative minors, neighbouring keys, chord motion |
| **Appendix · Chord types** | [`chord-types.html`](chord-types.html) / [`chord-types.md`](chord-types.md) | Every chord type — triads, sus, 6ths, 7ths, extensions, altered |
| **Appendix · Chord dictionary** | [`chord-dictionary.html`](chord-dictionary.html) / [`chord-dictionary.md`](chord-dictionary.md) | Every chord in all 12 keys, with a mini-keyboard under each — click to hear |
| **Appendix · Chord cheat-sheet** | [`chord-cheatsheet.html`](chord-cheatsheet.html) / [`chord-cheatsheet.md`](chord-cheatsheet.md) | Diatonic chords for every common key + go-to progressions |
| **Appendix · Play along** | [`songs.html`](songs.html) / [`songs.md`](songs.md) | Famous songs by progression — transpose, loop & practice chord changes |
| **Quest Mode** | [`quest.html`](quest.html) / [`quest.md`](quest.md) | Three tracks, lucky dips, echo & note-race games, streaks, points, stars |
| **Resources** | [`resources.html`](resources.html) / [`resources.md`](resources.md) | Best free theory, scores, and tools |

**Live site:** https://bikashacharya.com/piano/ — the landing links to [Sangeet Yatra](https://bikashacharya.com/) (singing, guitar, madal, tabla).

## How the pages fit together

Navigation (sidebar + landing) is grouped into five learning areas instead of one flat list:

- **Foundations** — [`theory.html`](theory.html): keyboard, connect your keyboard, reading teaser, scales & chords basics, 4-week plan.
- **Scales & modes** (basics → deeper) — [Scales](theory.html#scales) → [Modes](modes.html) → [Beyond scales](beyond-scales.html) → [Circle of fifths](circle-of-fifths.html).
- **Chords & harmony** (learn → reference → apply) — [Chord cheat-sheet](chord-cheatsheet.html) → [Chord types](chord-types.html) / [Chord dictionary](chord-dictionary.html) → [Play along](songs.html).
- **Technique & practice** (beginner → advanced) — [Drills](drills.html) → [Exercises](exercises.html) → [Hanon (Part I)](hanon.html) → [Training routines](routines.html).
- **Listen & read** — [Ear training](/tools/ear-training.html) · [Sight reading](reading.html) · [Time signatures](time-signatures.html) · [Note values](note-values.html) · [Highway](highway.html).

Plus **Quest Mode** (parallel gamified path) and **Resources**. Each cluster page also shows an "in this series" strip linking its siblings.

Open `index.html` locally, or serve the folder with any static host.

## Why this shape?

Forked from the structure of the [singing](https://github.com/Zither-Labs/singing) guide (landing → learning path → interactive practice → curated resources), then rewritten for **Western piano**: note names, major/minor, chords, and a **points-based Quest Mode** for learners who respond to challenges.

## Quest Mode progress

Quest Mode stores points and unlocks in `localStorage` (`piano-kids-quest-v1`) on that browser/device. Reset is on the Quest Mode page. Replays and hot streaks still add points so the high-score board keeps moving.

## Audio

`js/piano-core.js` plays a soft piano-ish Web Audio tone (no sample pack required). Works offline after first load.

## Metronome (every page)

`js/metronome.js` self-injects a pinned bottom **metronome bar** on every page (load it after
`piano-core.js`). It has a typeable tempo (40–208 BPM, read as the quarter note), a volume slider,
and a Beats selector for simple, compound and odd/irregular meters with grouped accents; the beat
unit matters, so a `/8` meter ticks twice as fast as the same numerator in `/4`. Other scripts read
it via `PianoMetronome` (`bpm()`, `beats()`, `denom()`, `beatMs()`, `volume()`, `start()`, `stop()`),
which is how the scale/mode "Hear it" players stay in sync with the tempo.

## Real keyboard input

The Theory and Practice page can react to a physical instrument:

- **MIDI keyboards** via the Web MIDI API (`PianoCore.enableMIDI()`) — exact and polyphonic;
  needs a secure context (https or localhost) and a browser that implements Web MIDI
  (Chrome/Edge on desktop). **Safari and iPadOS do not** — the connect UI hides the MIDI
  button and promotes the microphone (or on-screen keys). For USB MIDI on iPad, use the
  **Web MIDI Browser** app.
- **Acoustic pianos** via microphone pitch detection (`PianoCore.enableMic(opts)`) — monophonic
  (one note at a time). Noise handling: adaptive noise floor, clarity/confidence gate, band-limited
  pitch range, and median smoothing. The returned handle exposes `calibrate(cb, ms)`,
  `setSensitivity(0..1)`, and `getLevel()`; pass `opts.onLevel` for a live meter. The Theory and
  Practice page wires these to a Calibrate button, Sensitivity slider, and level meter.
  Shared helpers: `PianoCore.supportsMIDI()`, `midiUnavailableHint()`, `adaptConnectUi()`.

Live input drives the scale, chord, and ear-quiz drills. Subscribe with
`PianoCore.onInput(fn)`; events look like `{ type:'on'|'off', midi, velocity, source:'midi'|'mic' }`.

## Free learning stack (external)

See [`resources.md`](resources.md): musictheory.net, Open Music Theory, IMSLP, PianoPath, and how they fit with this app.