Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3,556 Commits

Folders and files

Repository files navigation

Handpan Theory

Chord flashcards and chord progressions for handpan scales. It runs in the browser with no account: https://handpantheory.com/

Practising with it

  • 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.

Scales

  • 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.

Your own scale

  • 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.

Printing

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.

Development

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.html is the whole app, and GitHub Pages serves it from main. There is no build step and no package.json.
  • data/decks.json is the one copy of the deck data.
  • The <!-- engine:... --> regions of index.html are copies of src/engine/*.js. python3 tools/inline_engine.py rewrites them.
  • The const DECKS line is rewritten from data/decks.json by python3 tools/sync_decks.py.
  • Do not edit either by hand. Both tools take --check, and python3 tools/validate.py fails if either drifts.
  • To fork, set GA_MEASUREMENT_ID in index.html to G-XXXXXXXXXX (this disables analytics) or your own id. Replace CNAME, the canonical, og and twitter:image URLs, both JSON-LD url values and the WebSite alternateName in index.html, robots.txt and sitemap.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 classes
  • src/engine/importer.js: product text, or the helper's four fields, to a scale string
  • src/engine/voicing.js: the cluster and spelling rules
  • src/engine/naming.js: chord symbols and subtitles
  • src/engine/select.js: which chords a pan gets, and in what order
  • src/engine/layout.js: the tonefield solver and label sizes
  • src/engine/share.js: share-link encoding
  • src/engine/sequence.js: progression loops
  • src/engine/swipe.js: the pure card-swipe core (thresholds, decisions, momentum)
  • src/engine/pdf.js: the PDF writer
  • src/engine/pdfdeck.js: adapts a deck for the print builders
  • src/engine/pdfcards.js: draws the cards, crop marks and calibration bar
  • src/engine/fontdata.js: font subsets, generated by tools/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).

License

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/.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages