Chord flashcards and chord progressions for handpan scales. It runs in the browser with no account: https://handpantheory.com/
- Tap a card to flip it. Swipe or use the arrow buttons or keys to move. SHUFFLE randomises the order.
- NAME → NOTES shows the chord name, then the notes. NOTES → NAME shows the lit pan, and you name the chord.
- A card shows the pan with every field of the chord's pitch classes lit, the root in one colour and the other tones in another. Below it are the notes and field numbers, in order from the root.
- The Chord progression group in the menu (EASY, MEDIUM, HARD) gives a loop of 2 to 6 chords to play.
- The browser remembers your scale, mode, progression tier and paper size.
- D Kurd 10: 49 cards
- D Amara 10: 29 cards
- D Amara 9: 27 cards
- C# Hijaz 9: 19 cards
- F3 Low Pygmy 18: 53 cards
177 cards total. D Kurd 10 opens first.
- Menu, then + ADD A SCALE. Type the notes on one line in any order: the ding in round brackets, bottom notes in square brackets (before or after the ding), a
|before inner notes. Example:[C] (D) A C D E F G A C. Octaves are optional: without one, we assume the notes run low to high. Then GENERATE CARDS. - ADJUST LAYOUT under the preview mirrors or reorders fields to match your pan, and slides bottom notes around the dashed ring in 5-degree steps; shared links keep the positions.
- Tap the selected scale's chip (it has a pencil) to edit or delete it. You can edit built-in scales the same way; RESET SEEDED SCALES brings them back.
- Scales stay in this browser. The link icon in the header copies a link that opens the scale on any device.
- A scale's id comes from a 32-bit hash of its notes. Two different scales can share an id, and then only one is kept.
DOWNLOAD PDF in the menu builds the chord cards for the shown scale in the browser. Pick Letter or A4. The cards are poker size, 3x3 per sheet. Print at 100% and check the calibration bar with a ruler.
Clone and run:
git clone https://github.com/raywu/handpan-cards.git
Open index.html from disk, or run tools/preview.sh to serve it at http://localhost:8000 with a LAN URL for a phone.
index.htmlis the whole app, and GitHub Pages serves it frommain. There is no build step and nopackage.json.data/decks.jsonis the one copy of the deck data.- The
<!-- engine:... -->regions ofindex.htmlare copies ofsrc/engine/*.js.python3 tools/inline_engine.pyrewrites them. - The
const DECKSline is rewritten fromdata/decks.jsonbypython3 tools/sync_decks.py. - Do not edit either by hand. Both tools take
--check, andpython3 tools/validate.pyfails if either drifts. - To fork, set
GA_MEASUREMENT_IDinindex.htmltoG-XXXXXXXXXX(this disables analytics) or your own id. ReplaceCNAME, the canonical, og andtwitter:imageURLs, both JSON-LDurlvalues and the WebSitealternateNameinindex.html,robots.txtandsitemap.xml. Tests and mutants pin the domain and the id, so update them too.
The engine is thirteen modules under src/engine/:
src/engine/core.js: note parsing and pitch classessrc/engine/importer.js: product text, or the helper's four fields, to a scale stringsrc/engine/voicing.js: the cluster and spelling rulessrc/engine/naming.js: chord symbols and subtitlessrc/engine/select.js: which chords a pan gets, and in what ordersrc/engine/layout.js: the tonefield solver and label sizessrc/engine/share.js: share-link encodingsrc/engine/sequence.js: progression loopssrc/engine/swipe.js: the pure card-swipe core (thresholds, decisions, momentum)src/engine/pdf.js: the PDF writersrc/engine/pdfdeck.js: adapts a deck for the print builderssrc/engine/pdfcards.js: draws the cards, crop marks and calibration barsrc/engine/fontdata.js: font subsets, generated bytools/inline_fonts.py
docs/ENGINE-SPEC.md is the spec and docs/SCALE_ENGINE_PLAN.md records the decisions.
Requirements: Node 22 and Python 3.12 (what CI uses), pip install -r requirements-ci.txt (reportlab, pymupdf, fonttools), and Chrome or Chromium for the browser tests. CHROME_BIN overrides where the tests look for it.
For browser checks, start with the shared browser validation runbook: it covers check selection, Mac setup and the unresolved full Mac timeout, serialized browser access, commands, evidence and cleanup. It is usable by humans, Claude, Codex and other command-capable harnesses; targeted local checks do not replace full exact-head CI and deployed DEV verification.
Tests:
./tests/run.sh # validate, boot sim, python and node suites
python3 tests/suite_health.py # per-file test-count floors
./tests/run.sh mutants # mutation gate (slow)
There are 30 node suites and 18 python suites. The mutation gate applies 1816 mutant patches from tests/mutants/, and a test must fail under each one. It edits the tree in place and refuses to start on uncommitted changes to a file a patch touches, README.md among them, so commit first.
CI runs on pull requests into main and on pushes to main. A PR that changes only docs/plans/ or docs/prompts/ skips every job.
More to read: CLAUDE.md (rules, verified layouts, design system), tests/CONTRACT.md (how to add a test), docs/plans/ (one plan per piece of work).
MIT, see LICENSE.
The SIL Open Font License 1.1 covers the fonts in tools/fonts/ and the subsets in src/engine/fontdata.js. It also covers their copies in index.html. See the OFL-*.txt files in tools/fonts/.