Overview
Harmonica.dev is a free music education platform that helps harmonica players build a mental map of their instrument. When you play piano, you can see your hands on the keys — your brain builds a spatial model of what you are doing. With harmonica, all the action happens inside your mouth. Your brain never gets what it needs to form that model.
Inspired by Lee Sankey's work on mental mapping for harmonica, I built a platform that makes the invisible visible: interactive diatonic charts showing the layout of notes for any combination of key, scale, and position, paired with audio tools so players can hear and practice what they see.
The Problem
Harmonica is one of the most popular instruments in the world, but learning resources have a gap. Existing charts and tab sites show you what to play, but not how the instrument is laid out across keys, positions, and scales. Players are left memorizing isolated patterns without understanding the system underneath.
A diatonic harmonica has 10 holes, each with blow and draw notes, across 12 possible keys. Add 12 positions and dozens of scales, and the combinatorial space is vast. Players need a tool that can show them any slice of that space instantly — and let them hear it.
Technical Approach
Configuration-Driven Chart Engine
At the core of the platform are two custom service layers: one for music theory and one for harmonica-specific knowledge. Music theory fundamentals — intervals, frequencies, note names, SPN — are all computed dynamically from first principles. The harmonica layer is configuration-driven: reed plate files define each hole as a set of scale degrees, and scale files define patterns as degree sequences. Adding a new harmonica type or tuning requires only new config files, no code changes. Tunings that share reed plates (differing by just one or two notes) can reference shared configurations. The result is a system that produces correct, detailed charts for any key, position, and scale combination from a small set of declarative files.
Lazy-Loaded Audio System
The practice tool lets players loop audio of any scale section with a configurable metronome. Under the hood it uses Tone.js, but the library is substantial — so it is lazy-loaded only when a user first interacts with the audio player. Audio context is carefully managed to handle browser autoplay restrictions and prevent resource leaks. Players can choose full scales, individual sections, or partial runs, and configure note length, BPM, volume, ascending or descending order, and whether to include notes that require advanced techniques.
Programmatic SEO at Scale
The same service layer that powers the charts also powers SEO. With 12 keys, 12 positions, and 15 scales, the platform generates 2,160 unique pages — each with genuinely distinct content computed from the underlying music and harmonica models. These are not thin pages with swapped keywords; each page contains a unique chart, unique note listings, and unique descriptive content specific to that exact combination. The site is being indexed rapidly, with Google Search Console showing strong early traction.
Results
The site launched recently and is showing strong early signals:
- 2,160 unique pages generated from configuration
- 200+ pages indexed by Google and growing
- Early Search Console milestones achieved ahead of typical timelines
Metrics will be updated as the site matures.