Introduction

Harmonicon is a rhythm game for real harmonica. You play an actual diatonic or chromatic harmonica into your computer’s microphone; Harmonicon listens, detects the pitch you’re playing in real time, and scores it against a chart scrolling across the screen — the same idea as any note-highway rhythm game, except the “controller” is an instrument you already own (or are learning), and every note you score is a note you actually played correctly.

The goal isn’t just a high score. Harmonicon is built to teach blues and jazz harmonica through play: a structured Lessons curriculum takes you from your first clean single note through bends, chords, and improvising over a 12-bar blues, and every scored mode gives you honest, per-technique feedback (not just “hit” or “miss”) so you know exactly what to practice next.

What’s in this book

• Getting Started — installing Harmonicon and getting your microphone working.
• Playing — the 2D and 3D scored modes, free-play Jam Session and its instant Generate a Jam backing, and the Bending Trainer ear-training drill.
• Lessons — the guided curriculum, unit by unit.
• Song Editor — for authoring or editing your own charts.
• Settings — Options, input-lag calibration, and visual themes.
• Controls Reference and Troubleshooting for when something doesn’t behave the way you expect.

If you’re brand new, the in-game Guided Tour (Main Menu → Help / About → Tutorial) gives you a click-free, under-a-minute walk through every top-level screen — including a few live seconds of actual gameplay — a good first stop before diving into this book.

Getting Started

Running Harmonicon

Harmonicon is a native desktop application (Windows, macOS, Linux — see the project’s release page or your package manager for a prebuilt binary). If you’re building from source:

cargo run --release

You’ll need a display, audio output, and a microphone — Harmonicon listens to your harmonica through the mic the same way it plays music through your speakers/headphones.

What you need to play

• A harmonica. Diatonic (10-hole, any key) and chromatic (12- or 16-hole) harmonicas are both fully supported. If you don’t have one yet, a diatonic harp in the key of C is the standard beginner’s choice and matches most of the bundled Lessons content.
• A microphone. A laptop’s built-in mic works, but a dedicated mic (even a cheap USB one) picking up less room noise will make pitch detection noticeably more reliable. Position it close to the harmonica, not close to your mouth.
• Headphones are recommended over speakers — they stop the backing track/metronome from bleeding into the mic and being misread as notes you played.

Picking your microphone

Harmonicon uses whatever input device your system reports as default, but you can pick a specific one from Options → Microphone: a dropdown lists every input device your system exposes. If the game shows a “no microphone” warning banner, open Options and confirm a working device is selected — see Troubleshooting if none of them pick up sound.

Before your first scored song, it’s worth a quick trip to Calibrating Input Lag — every microphone and audio setup has a slightly different delay between the sound leaving your harmonica and Harmonicon detecting it, and correcting for it is a one-time, 30-second step that makes every subsequent judged note more accurate.

Adding your own content

Harmonicon also reads from ~/Harmonicon (a folder in your home directory) as a second source of songs and themes, alongside what ships with the game — drop a song folder or a theme folder in there and it shows up in the song list / theme picker without needing to reinstall anything. See Song Editor for how to author a chart of your own.

A song folder only strictly needs one thing: a .harpchart file (any filename) inside its song/ subfolder. Everything else is optional — background.png, song/*.ogg for the backing track, and the 2d//3d/ note art folders — Harmonicon fills in a generated background, plays no backing track, and falls back to the selected note theme respectively for whatever’s missing, rather than refusing to load the song.

The Main Menu

The Main Menu is Harmonicon’s home screen, with four buttons:

• Play — opens the Play menu: play a real song, create one, jam freely, practice bends, or work through the lessons.
• Options — audio, note style, harmonica model, and microphone settings. See Options.
• Help / About — documentation, information about the app, the guided tour, and credits. See Help / About.
• Quit — exits the game.

Press Esc on any menu page to go back one level; there’s no dedicated Back button needed on the Main Menu itself, since it’s the top of the hierarchy.

The Play Menu

Main Menu → Play is where every way of picking up the harmonica starts:

• Play Song — the scored song flow. See Playing a Song.
• Create Song — opens the chart authoring tool. See Song Editor.
• Jam Session — a submenu with two ways into free play: Pick a Song (jam over a real song’s backing, see Jam Session) or Generate Jam (synthesize an instant backing with no song required, see Generate a Jam).
• Bending Trainer — isolated bend practice. See Bending Trainer.
• Lessons — the guided curriculum. See Lessons.

Press Esc, or click Back, to return to the Main Menu.

Playing a Song

Play → Play Song starts the scored song flow:

1. Select Mode — choose Play 2D (a scrolling note highway) or Play 3D (a 3D harmonica model you play along with). Both modes share the same scoring, timing, and pause menu — it’s purely a visual choice.
2. Select Artist, then Select Song — browse the bundled songs (and anything you’ve dropped into ~/Harmonicon/songs/, see Getting Started).
3. A 3-2-1 countdown plays, showing the song title, key, and which physical harmonica to grab, then the chart starts scrolling and the backing track plays.

Scoring

As notes reach the hit line, Harmonicon compares the pitch it hears against what the chart expects, at that instant:

• Perfect / Good hits, based on how close your timing was to the note’s onset.
• Miss, if the window passes with nothing (or the wrong pitch) played.
• Longer notes reward holding the correct pitch for their full duration, not just landing the onset.
• Special techniques — bends, vibrato, wah, overblow/ overdraw, and (chromatic only) slides — are validated on their own terms, not just “was some pitch playing”: a bend note checks you actually bent to the target pitch, a vibrato/wah note checks the oscillation rate you played matches what the chart asks for.
• Chords and octave-split notes only score when every note in the group sounds together — playing the same holes correctly but one at a time doesn’t count.

A combo multiplier builds on consecutive hits and resets on a miss. The Results screen after each song breaks your accuracy down by technique (not just an overall percentage), so you can see at a glance whether it was your bends or your timing that need work.

Pausing and quitting

Press Esc, or click the ⏸ button in the bottom-right corner, to pause mid-song — the on-screen button works the same as Esc, no keyboard required. The pause menu is two columns: Resume / Restart / Quit Song on the left, every practice aid on the right, so a slip of the mouse over one can’t misclick the other. The practice aids:

• Wait for Note — freezes the highway and music the instant an unhit note reaches the hit line, and holds there until you play it — useful for slowing down a hard passage without losing your place. There’s no way to “miss” a frozen note; it just waits.
• Practice Speed — a slider from 50% to 100% that slows the highway and metronome without pitch-shifting the audio; it mutes instead below 100%, so you never hear a chipmunked backing track.
• Adaptive Difficulty — off by default (turn it on in Options, under Audio); once on, a song’s notes unlock gradually as you clear each phrase cleanly, instead of throwing the full chart at you immediately. This is one setting shared by every song, not something you pick per song. To override a specific phrase, click its rectangle on the song-progress bar’s bottom strip (it highlights gold once selected) and drag the Learned slider that appears below — or flip the pause menu’s own toggle to switch it off/on immediately, mid-song (this also updates the Options-menu setting).
• A–B Looping — drag on the song-progress bar at the top of the screen to mark a section and loop it, for drilling one phrase repeatedly. Clear Loop removes it.

See the Controls Reference for every in-game keybinding.

Play 2D

The 2D mode shows notes as a falling note highway: ten lanes (one per harmonica hole), each note a colored “comet” with a tail sized to its duration, scrolling down toward a fixed hit line.

• Notes are colored by breath direction — blow and draw each get their own color, shown in the legend beside the highway.
• A note recolors gold the instant it’s hit, and red if it’s missed.
• The hole strip along the bottom mirrors your harmonica, live — useful for double-checking which hole/direction a note actually wants without reading the lane position.
• Optional hole-number labels (Options → Note labels) replace the plain up/down arrow on each note with its actual hole number, if you’d rather read “4” than work out the arrow from the lane.
• The metronome, technique legend, and score/combo sit in the HUD to the side of the highway. Authored phrase and chord labels appear in the phrase banner; gameplay does not invent a blues progression for a chart that does not contain one.
• A tab-notation ribbon shows the current musical phrase’s notes as plain text (e.g. -4' +5 -4) as they come up — handy if you’re more comfortable reading harmonica tab than the highway.

Everything else — scoring, pausing, looping, adaptive difficulty — works identically to Play 3D; see Playing a Song for the shared details.

Play 3D

The 3D mode shows the same chart, notes, and scoring as Play 2D, but renders a 3D harmonica model in front of the camera with notes flying toward it — a more immersive, “you are holding this harmonica” view of the same gameplay.

• The harmonica model matches your selected note theme/harmonica model (Options), and reacts live to what you actually play.
• Optional hole-number labels (Options → Note labels) show as small dark pills near each incoming note, the 3D equivalent of 2D’s on-note labels.
• Chromatic harmonicas don’t yet have a dedicated 3D model — a diatonic model is shown in its place if you’re playing a chromatic chart in 3D.

Scoring, the HUD, pausing, A–B looping, Wait for Note, Practice Speed, and Adaptive Difficulty all work exactly as described in Playing a Song — 2D and 3D are purely a visual choice made once, at Select Mode.

Jam Session

Play → Jam Session → Pick a Song is free play: pick an artist and song the same way as Playing a Song, but instead of scored falling notes, you get an open 12-bar backing to improvise over, for as long as you like — there’s no finite end and nothing is scored.

The screen is split into two columns:

• Left — everything but the harmonica: the song title, a Loop toggle (restarts the backing track when it ends, instead of stopping), the 12-bar chord grid (the current bar lights up as the backing plays), the metronome, and a live spectrogram of what your mic is hearing.
• Right — the harmonica: a reference bend diagram for every hole, plus a live-tinted hole map — as you play, each hole/direction recolors: gold for a chord tone of the bar currently sounding, green for anywhere else in the blues scale, and left dim for out-of-scale notes. Follow the color, not memorized theory.

There’s no “wrong note” here in the scored sense — the hole map is a guide, not a judge. It’s the same live feedback the improvisation lesson uses, so practicing here and in that lesson builds the same skill.

Want a backing track without picking an existing song? See Generate a Jam.

Press Esc, or click the ⏸ button in the bottom-right corner, to pause and reach the pause menu’s Restart/Quit Session controls.

MIDI backing with per-track muting

If the song you picked was authored from a MIDI file that kept its original tracks (rather than one pre-mixed backing track), a row of buttons appears below the 12-bar grid and the harmonica, one per track, each showing 🔊 next to the track’s name. Click one to mute it — it switches to 🔇 and drops out of the mix instantly, with no effect on the other tracks or on timing; click it again to bring it back. This is handy for stripping out a bass or rhythm track you’d rather play yourself, or just hearing what one part of the arrangement sounds like on its own. Mute state resets to “everything audible” each time you start the jam, and — if Loop is on — carries over unchanged when the backing loops back to the start.

Generate a Jam

Play → Jam Session → Generate Jam skips picking a song entirely: it synthesizes an endless 12-bar backing on the spot (a swung “blues box” bass line, not a second harmonica part), so you can jam without needing any existing content.

Before starting, pick:

• Key — a dropdown of all twelve chromatic keys.
• Progression — Standard (I-I-I-I-IV-IV-I-I-V-IV-I-V, the classic 12-bar form), Quick Change (moves to the IV a bar early), Minor Blues (the i/iv chords become minor), or Jazz Blues (a ii-V-I cadence in the last few bars).
• Position — which cross-harp position to play in: 1st (straight harp, same key as the jam), 2nd (cross harp, the classic blues choice — a harp a fourth below the jam key), or 3rd (a harp a whole step below).
• Tempo — type a BPM value directly (60–160; out-of-range or non-numeric input is clamped/corrected once you press Enter or click away).

Click Start Jam and you’re straight into an ordinary Jam Session — same two-column layout, same live hole-map feedback, same 12-bar grid — just with a generated backing instead of a real song’s. Restart resets the bass to the top of the loop; Quit Song returns to this setup page (with your key/progression/position/tempo remembered), not the song list, since there was never a song list involved.

Bending Trainer

Play → Bending Trainer is a standalone ear-training screen — no song, just the harmonica’s full bend diagram, a metronome, and a pitch tuner, for practicing bends (and overblows/overdraws) in isolation.

The title sits top-left and Back top-right, the same header every other screen uses. Below it, the screen splits into two columns:

• Left — everything but the harmonica, grouped into four sections:
  • Setup — a Key picker and a Detect algorithm picker (which pitch-detection method to use — the same setting Options uses), both dropdowns.
  • Practice Target — the current target readout, a Listen button (plays a synthesized reference tone for it), and a live cents-off tuner readout.
  • Drill — the adaptive Drill toggle; hovering it explains what it does.
  • Tempo — the metronome and its BPM steppers.
• Right — the harmonica: the full bend diagram (every hole’s blow, draw, bend, overblow, and overdraw notes), with its explanatory hint text beneath it.

Picking a target

Click any cell in the bend diagram to make it the current target — its note name appears in the target readout, and Listen plays a clean synthesized reference tone for it so you know exactly what pitch you’re aiming for before you try to bend to it. The cents-off tuner then tells you, live, how far off (and in which direction) the closest pitch you’re actually playing is.

Drill mode

Turn on Drill and Harmonicon picks targets for you, weighted toward ones you haven’t tried yet or have a lower accuracy on — a spaced-practice loop instead of you deciding what to work on. Your hit rate per hole/technique is saved across sessions, so Drill mode gets smarter about what you personally need to practice the longer you use it.

Leaving

There’s no pause menu here (there’s no song to pause) — click Back in the header, or press Esc, to return to the Play menu. Either way your drill progress is saved on the way out.

Lessons

Play → Lessons is a guided curriculum, drawn as a skill tree. Along the top runs a row of unit nodes — Unit 1, Unit 2, and so on — and each unit’s lessons hang below it, connected by the order you take them in. The tree is wider and taller than the window: scroll in both directions to see the rest of it.

There are two locks. A lesson shows dark until you’ve passed whatever it leads on from — hover it and the tooltip names what it’s still waiting on. A whole unit stays shut until you’ve passed most of the one before it; the number on a unit node (“3/8”) is how many of its lessons you’ve done and how many open the next unit. It’s most, not all — one lesson you’re stuck on shouldn’t wall off the rest of the course.

Colour is the skill each lesson belongs to (bending, rhythm, tone…). Some nodes also carry a ring of dots above them: that’s a training ladder, and the filled dots are how much of it you’ve cleared. A ladder is five drills on the same technique, each harder than the last — isolated and slow, then faster, then across every hole the lesson covers, then inside a phrase, then shuffled so you can’t run it from memory. The bend lessons are the ones that have them; a lesson with no ring has no ladder. A passed lesson stays replayable any time, and your progress is saved (profile.json) and survives restarting the game.

Clicking a lesson — locked or not — opens its reader page: instructional text explaining the technique, a goal line (e.g. “Goal: 70% overall accuracy”), a Start Lesson button, and the ladder’s tiers if it has any.

About twenty lessons show Mark as Done instead. Those are pure instruction with nothing to score — tongue blocking, for instance, which the microphone genuinely can’t tell apart from puckering, or the practice-skills lessons, which are about how you work rather than what you play. Rather than pretend to grade them, the game asks you to say when you’ve read and understood them.

Practice tools on the page

Some reader pages carry interactive tools below the explanation, there to play with before you start the drill. They never affect your score — completion still comes from Start Lesson or Mark as Done.

• Circle of fifths — the twelve keys arranged so each neighbour is a fifth away, with the harp’s key at the top and its playing positions marked. Step it up or down a semitone to see the same relationships from another harmonica’s point of view; position lessons show only the position they’re teaching, so the picture stays uncluttered.
• 12-bar grid — the form laid out as twelve boxes, coloured by chord. Step the highlight forward or back a bar, or reset it to the top. The chords shown follow whichever progression the lesson is about: the standard blues, a quick change, a minor blues, or the jazz blues.
• Metronome — start and stop it, nudge the tempo by 5 BPM either way, switch between straight, shuffle, and equal-triplet pulses, and mute the click if you’d rather watch than listen. Some lessons change tempo after a configured number of bars to demonstrate an accelerando.
• Form map — a row of named sections such as A–A–B–A. Repeated sections share a colour, and Previous/Next lets you follow the form as you listen.
• Rhythm pattern — a strip of counted subdivisions. Dark cells are rests, accented cells carry a > mark, and Previous/Next lets you trace exactly where an attack or silence falls.
• Phrase looper — an A-to-B strip of short tab or practice cues. Start it to watch the active cell repeat at the displayed tempo, adjust that tempo in 5 BPM steps, or move through the phrase by hand. It marks practice time; the lesson’s playable drill supplies the sound.

When a page shows a metronome and a grid together, starting the metronome walks the highlight through the form — one bar per bar, in the feel you picked. That pairing is the whole point of lessons like Counting the Bars and The Turnaround: you hear where you are and see where you are at the same time.

Core units and electives

The curriculum runs to a hundred lessons across seventeen units. Units 1 to 6 are the numbered core course, taken in order; three more — Rhythm lab, Applied positions and Ear training — continue it without numbers, and gate the same way. Everything else is an elective.

An elective is exactly what it sounds like: worth your time, never in your way. It can have prerequisites of its own, but it never counts toward a unit’s gate and never holds up the required course. You can spot one on the tree without reading anything — the branch leading to it is dotted and a different colour, and the lesson carries a small badge. It’s a hue, not a dimming, because dimming already means locked and an elective is perfectly playable.

Eight units are electives end to end. Their unit nodes take the same colour, and their number counts your progress through them (“2/6”) rather than a threshold, because there’s nothing to unlock. They still sit behind the units before them in the course, and read as locked until you get there.

Unit 1 — Blowing the Harmonica

Single clean notes, chords, tongue blocking, octave splits, slides, and hand-shape/wah — the physical fundamentals of getting a controlled sound out of the instrument, before rhythm or improvisation enter the picture. Breathing and long tones, your first bends (working up to the deep 2- and 3-draw bends 2nd-position blues lives on), vibrato, and “ta-ka” tongued articulation round out the fundamentals.

Unit 2 — Counting the Blues

The 12-bar form, playing in time, call-and-response (Harmonicon plays a short phrase, you echo it back — the game waits for you, however long you need), and finally improvisation: the only lesson with no fixed notes to hit at all. It opens an ordinary Jam Session and judges you on how much of what you played landed on a chord tone or in the blues scale, via the same live hole-map coloring Jam Session itself uses. When you feel done, open the pause menu and click Finish Lesson. Counting drills (four-on-the-floor down to just beat 1, then a full 12-bar walk of chord roots and the turnaround that leads back to the top), a straight-vs-shuffle feel drill, and the classic train chug — including a chorus that genuinely speeds up — round out the unit.

Most drills are scored exactly like a normal Play 2D song underneath — same falling notes, same HUD — with the pass/fail judgment layered on top of the ordinary results screen instead of a song’s usual best-score tracking.

Unit 3 — Blues Vocabulary

The bridge from drills to music. You start with the 2nd-position blues scale itself, then learn three short original licks call-and-response style — the game plays each one, you echo it back — followed by a set of licks built specifically around the “crying” bent notes, and finally a full 12-bar chorus that places a different lick over each chord.

From there it’s four more open-jam lessons, each judged on a different slice of your playing: land specifically on chord tones as the chords change (not just anywhere in the scale), improvise over a minor blues progression instead of the usual major one, leave real space by playing two bars and resting two, and handle a quick change — where the IV chord arrives in bar 2 instead of bar 5. They all use the same “Finish Lesson” pause-menu flow as Unit 2’s improvisation lesson, and the two that change the form put a 12-bar grid and a metronome on the page so you can hear it before you play over it.

Unit 4 — Scales and Improvisation

The major scale, the minor pentatonic and the country scale as playable drills, then the major and minor pentatonic again as open jams where what’s scored is how much of your playing stayed inside them. The unit closes on the circle of fifths: an instructional page with the diagram on it — rotate it to any harp key and see which position lands you in which key — followed by a jam that calls out a new position every few bars, so you play that relationship instead of just reading it.

Unit 5 — Jazz

Swing eighths, the ii-V-I outlined in chord tones, and the jazz blues form — the 12 bars with the substitutions that turn a blues into a standard, with a grid and metronome on the page to hear the difference. One elective introduces the chromatic harmonica’s slide button.

Unit 6 — Finding Your Way Around

Knowing the layout without hunting for it. Landmarks on holes 1, 4, 7 and 10; the middle, low and high registers on their own; clean jumps between holes; the two awkward crossings every diatonic player meets (3-to-4 and 6-to-7, where the breath pattern changes direction); and finally leaping across registers in one phrase.

Rhythm lab, Applied positions, Ear training

Three more gated units continue the course past Unit 6:

• Rhythm lab — eighth-note triplets, straight against shuffle with a metronome you can flip between the two, syncopation and rests, sixteenth-note articulation, and holding a tempo without drifting.
• Applied positions — landing notes for 1st, 2nd and 3rd position, each with a circle of fifths showing just that position.
• Ear training — four lessons that hide the scrolling notes. You hear a note, a shape (up, down or the same), or a whole phrase, and play it back. See the note on these below.

The elective units

The rest of the tree is optional. Nothing here gates anything, so take what you need:

• Advanced electives — high blow bends on holes 8–10, overblows and overdraws: the notes a diatonic harmonica isn’t supposed to have.
• Tongue-block electives — slap, pull, side pull, rake, flutter and moving octaves. Mostly instructional: the microphone can’t tell a tongue-blocked note from a puckered one, so these are explained and marked done rather than scored.
• Ornaments — the slow warble, the fast shake, trill cells and glissandi.
• Expression — hand, throat and diaphragm vibrato, controlling vibrato rate, crescendo and diminuendo, and long-tone control.
• Accompaniment — playing behind somebody: chord rhythm, staying out of a singer’s way, fills between lines, and trading fours.
• Chromatic harmonica — button coordination, choosing between enharmonic slide fingerings, chromatic fragments, legato phrasing across the slide, and an original jazz study, Crossing Lights.
• Musicianship — intervals, building chords, guide tones, arpeggio into scale, transposition (with a circle of fifths to work it out on), and listening for form.
• Practice skills — how to practise rather than what: slow practice, isolating a loop, spaced review, recording yourself, and mixed review.

Ear-training lessons hide the notes

The ear-training unit runs on the ordinary gameplay screen with the falling-note prompts turned off. The call still plays, scoring still works exactly as it does everywhere else, and the HUD still tells you how you did — you just have to find the note by ear instead of reading it off the highway. If a run feels broken because nothing is scrolling, that’s this, working as intended.

Song Editor

Play → Create Song is Harmonicon’s chart authoring tool — a piano- roll-style grid for building or editing a .harpchart file by hand, without writing JSON directly.

Layout

The screen has three parts:

• The tool sidebar down the left edge, in two columns. The left column is about the song and the tools: Back, the mode buttons, lock, undo/redo, copy/paste, the Select/Erase/Remove/Tempo tools, metronome, legend, and Save/Load. The right column is about the note — the selected one, or the next one you’ll place: Blow/Draw, bend/overblow/ overdraw (or slide), wah/vibrato and their depth, the phrase’s Call and Split marks, the phrase editor, and Delete. With nothing selected the right column previews what a newly placed note gets, so it’s never empty. It only appears in Edit mode; Record and Play fold the sidebar back to one column and give the grid the width. Either column scrolls — drag it or use the mouse wheel over it — because on a short screen the whole palette doesn’t fit at once.
• The note grid, one lane per harmonica hole, under the Chart tab.
• The song’s metadata (tempo, key, position, title, background music, and the lesson fields) under the Details tab.

Chart and Details are tabs rather than stacked panels so the grid gets the full height of the window — on a laptop screen, and especially on a phone, the grid alone can fill it.

The sidebar’s buttons can show icons only, text only, or both — set it under Options → Button style. Icons-only makes the sidebar much narrower and is what puts the two columns side by side; with text labels they stack into one column instead. Every button keeps a tooltip either way, so hovering always tells you what it does.

Modes

• Edit mode — place, move, resize, and delete notes on the grid. Click an empty cell to add a note; drag a note’s edges to resize it or its body to move it. The sidebar’s note column sets the selected note’s technique: Blow/Draw direction, bend depth, overblow/overdraw, slide (chromatic only), wah/vibrato rate and Depth (¼ ½ ¾ 1, stepped by clicking, like the rate), or delete it outright. Ctrl+click adds or removes a note from the selection instead of replacing it, so you can select several at once; dragging any one of them moves the whole group together, keeping their relative positions (mod-panel technique edits still only ever act on the last-clicked note — editing several notes’ technique at once has no single obvious meaning).
• Record mode — play your harmonica and have it write notes onto the grid for you, with its own Play/Pause/Stop/Finish transport (see Recording notes live below).
• Play mode — plays the chart back (▶ Play / ⏸ Pause / ■ Stop), or switches to Practice: play along on your actual harmonica and get the same live pitch feedback a real song gives, against the chart you’re currently editing — the fastest way to sanity-check a chart actually feels right before saving it.
• Lock — freezes the grid against accidental edits while you’re just reviewing or practicing.

When a song runs wider than the window, a horizontal scrollbar appears under the grid — and it doubles as a minimap: every note shows as a tiny blow/draw-colored rectangle at its place in the full song, so you can see at a glance where the phrases are and drag straight to them.

Grid snap: Straight, Shuffle, Triplet

The Grid Snap button (next to the harmonica-type toggle) cycles between three subdivisions of each beat, controlling where a note lands when you place, move, or resize it:

• Straight 16ths — the default; four evenly-spaced positions per beat.
• Shuffle — a 2:1 long-short swing pair, the classic blues shuffle bounce (the first and third notes of an 8th-note triplet, skipping the middle one).
• Triplet — three equal subdivisions per beat, for licks and turns that are genuinely triplet-based (slow 12/8 blues, train rhythms).

Straight 16th positions and triplet positions are marked on the grid in two different colors (see the color legend) so you can see at a glance which subdivisions are which, regardless of which mode is currently active. Switching modes only changes where the next placement, move, or resize lands — it never moves notes that are already sitting off-grid.

Chart metadata

The meta-form covers a chart’s song-level fields: music tempo, harp key, playing position, harmonica type (standard, Paddy Richter, country-tuned, or natural-minor 10-hole diatonic; 12-/16-hole chromatic), background music file, and song name/author — everything under song and harmonica in the .harpchart format.

Section, Chord, and Groove describe the phrase that begins at a note. Select a note and press the sidebar’s Phrase (§) button, and a small panel opens above the grid with the three fields — enter a section name such as Verse 2, a chord symbol such as G7, or feel guidance such as laid-back shuffle. Notes that begin on the same tick share the annotation. Clearing every field removes that marker from the chart. These are phrase properties, not song ones, which is why they live beside the note tools rather than in Details.

These phrase values are also visible in the header above the notes. Section boundaries use §, chords use ♬, call-and-response uses ↩, and a tongue-block split uses TB; hover a clipped marker to read its full contents. Markers stop at the next phrase anchor, so dense annotations do not cover the note lanes or resize handles.

Click a marker to edit it in place. A small panel opens just below it with the Section, Chord and Groove fields for that phrase, and every note that starts there is selected — so a drag or Delete right after acts on the whole phrase. Press Escape or the panel’s ✗ to close it; it also closes by itself if the phrase’s notes are removed.

When the selected note has vibrato or wah, the Depth button in the note column steps its depth ¼ → ½ → ¾ → 1; ½ is the default. The button shows the current value, and with nothing selected it shows — and sets — the depth a new note will get. A chart can carry any depth in between; the button shows it as-is and a click steps up to the next quarter. The rate still comes from repeated clicks on the Vibrato or Wah button.

Select a note and press the sidebar’s Call (↩) button to make the phrase beginning there a response exercise. During gameplay Harmonicon demonstrates consecutive call-marked phrases, then waits for the player to perform them. The button lights while the selected note’s phrase is a call.

For an octave or tongue-block split, place the simultaneously sounding notes at the same tick with the same duration, select either note, and press Split (TB). The chart then labels that group as a split rather than an ordinary chord.

Tempo changes

A song doesn’t have to hold one flat tempo. Selecting the Tempo tool (next to Select/Erase/Remove) and clicking the ruler above the grid drops a tempo-change marker at that beat, shown as a ♩=<bpm> label on the grid header; clicking near an existing marker removes it instead. Each new marker starts at a step above whatever tempo is already in effect there, so building up to a faster or slower section is a few clicks. The waveform (if the chart has one) and the beat/bar grid both lay out against the real tempo map, so they stay aligned across a tempo change instead of drifting.

Time-signature changes

Select the Meter tool and click the ruler to add a time-signature change on the nearest beat. A new point starts at the next available signature; clicking the point cycles it again, and cycling back to the preceding meter removes it. The opening meter remains controlled by the Time Signature picker in Details. Meter changes begin a new bar and are labeled directly on the ruler, so later bar numbers, beat numbers, and the 12-bar tint stay aligned.

Scale and note colors

Every note on the grid is tinted by the technique it’s played with — plain blow/draw, bend, overblow, overdraw, or slide — and gets a warm red tint blended in if it falls outside a reference scale, as a gentle “you’re reaching outside this scale” flag rather than an error. The third column next to the meta-form fields is a full legend for every color the editor uses, in case any of this is unclear at a glance.

The Scale field, in the Details tab, picks that reference scale:

• 1st/2nd/3rd Position — the blues scale, rooted at the harp’s own key, a fifth above it, or a whole step above it respectively (matching the three classic cross-harp playing positions).
• Major Scale / Minor Pentatonic / Country Scale — rooted directly on the harp’s key, for melodies that aren’t blues-flavored at all.

It defaults to 1st Position, and only affects this warning color — it never changes which notes you can actually place.

Auditioning a note

Clicking a note plays a short blip of exactly what it sounds like — the same synthesized harmonica voice used everywhere else in the editor — so you can confirm a bend, overblow, overdraw, or slide actually sounds right without reaching for Play/Practice or a real harp. It only fires when the selection actually changes to a different note; clicking the same note again doesn’t replay it.

Authoring a lesson

The Recording field in the meta form cycles between Record Song and Record Lesson. Switching to Record Lesson doesn’t change anything about editing notes, playing back, or practicing — it just adds a curriculum layer on top of the chart you’re building, so a lesson’s chart is really just an ordinary chart with some extra metadata attached.

Click the ▸ Lesson Details header to expand the curriculum fields (collapsed by default, so it stays out of the way while you’re just placing notes):

• Lesson ID and Unit — the lesson’s identity and which curriculum unit it’s grouped under in the Lessons list.
• Explanation — the instructional text shown on the lesson’s reader page.
• Prerequisites — a comma-separated list of lesson IDs that must be passed first, before this one unlocks.
• Pass Criteria — how the lesson is judged: an accuracy threshold, a specific technique’s accuracy, or (for an open-jam lesson with no fixed notes) scale adherence, chord-tone adherence, or phrase discipline. Threshold and Technique only appear when the chosen criterion actually needs them.
• Progression — the backing chord progression an open-jam lesson starts with (standard, quick-change, minor, or none).

Saving writes a lesson.json file (validated against the lesson schema before writing) alongside the chart, if the grid has any notes on it. One thing lesson.json can’t do: it stores the lesson’s title and explanation as Fluent keys, never the actual display text you typed — Harmonicon’s translated-text system needs real entries in each supported language’s locale file, which this tool can’t generate for you. After saving, check the game’s log/console: it prints the exact key/text pairs to add by hand.

A lesson save doesn’t carry over a MIDI-imported backing track — author the chart as an ordinary song first if it needs one, then switch to Record Lesson to add the curriculum fields on top.

Erasing and removing parts of a song

The Select tool in the sidebar (next to Delete) turns the ruler above the grid into a range selector for a whole span of time rather than one note at a time — handy for a song built from an imported MIDI track that starts later than beat 1, or just cutting a section you don’t want.

With Select active: click-drag-release across the ruler to pick a range — and if the range you want runs past the edge of the screen, just wheel- scroll while still holding the drag; the grid pans, newly revealed notes appear, and the selection keeps growing to follow. Alternatively, click a point on the ruler to drop a split marker, then click either side of it to select everything from there to that edge of the song.

The selection itself changes nothing. With a range selected, the Erase and Remove buttons act on it — a confirmation dialog names the exact range before anything happens. Erase deletes the notes in that range and leaves a gap; Remove deletes them and shifts every note after the range earlier to close the gap, shortening the song. Tempo and meter changes move with the later notes, and the timing active at the end of the cut remains active at the new join. Escape clears a selection or pending split marker.

Silence track

A thin strip below the last hole lane, labeled “Silence”, shows the gap between consecutive notes as a block giving its length in seconds — useful for spotting an unintentionally long rest, or confirming a deliberate one lines up with the phrasing you meant. A chord, or notes placed back to back with no rest between them, shows no block; there’s also none before the first note or after the last, since there’s no gap to measure there. It’s purely a display — nothing on it is clickable.

Importing MIDI

Import MIDI loads a .mid/.midi file and lists its tracks in a dropdown; picking one drops that track’s notes onto the grid, mapped onto your currently selected harp key and type — an exact note where one exists, a bend or (on a chromatic harp) a slide where one doesn’t, otherwise the nearest playable note — and sets the chart’s tempo and time-signature maps to match, including changes later in the song. After import, the status bar reports notes that had to be approximated, same-onset chords that mix blow and draw, and chords that map multiple notes to one hole. The notes stay on the grid so you can inspect and rewrite those phrases. Switching the dropdown to a different track re-imports from that track instead.

Saving while a MIDI track is selected also writes two extra files next to the chart: a copy of the MIDI file with the imported track removed (your original file is never touched), and a synthesized backing track — song/music.wav — built from every other track in the file, since Harmonicon can’t play a raw MIDI file directly. That backing track plays automatically both in the editor’s own Play preview and, once the song is in place, during the real game.

Metronome and count-in

The 🔔 Metronome button (next to Undo/Redo) toggles a click track that plays during Record, Play, and Practice — the same click, tempo, and shuffle/straight feel setting as gameplay’s own metronome, so your mute preference carries over between the two. Starting a fresh Record take (not resuming a paused one) counts in one full bar first, with a “get ready” countdown in the status bar, before recording actually begins — enough time to get your harmonica up and settled into the groove before the take starts.

Recording notes live

Record mode writes a chart by ear, with a transport of its own:

• ▶ Play starts a take from the current playhead position — the beginning on a fresh take, wherever you clicked on the ruler, wherever the last take stopped, or (resuming) wherever you paused. The chart’s background music plays from that same position.
• ⏸ Pause freezes the take in place — whatever note you’re holding is closed right there — and Play (or Pause again) resumes exactly where you left off, as the same take.
• ⏹ Stop ends the take and leaves the playhead where it stopped, so the next take can pick up from there.
• ⏹ Finish ends the take and rewinds to the beginning — you’re done, or ready to re-record the passage from the top.

While no take is running, clicking the ruler above the grid moves the red playhead line to that spot; Play then records from there — the quickest way to punch in on a specific passage.

Each note appears on the grid the instant you start playing it and keeps growing for as long as you hold it, so you watch it take shape in real time rather than only seeing it once you stop. Notes are mapped onto your currently selected harp key and type exactly the way MIDI import maps a file’s notes (an exact note where one exists, a bend or slide where one doesn’t) — a bend you actually play and hold is recorded as a bend, not snapped to the nearest natural note. The status bar shows a running count of notes captured while you play.

Recording punches in: a note you play replaces whatever the grid already had at that moment — notes from an earlier take, imported or hand-placed ones — instead of stacking impossible blow-and-draw-at-once combinations on top of them. Notes played earlier in the same take (including the other notes of a chord) are never touched, and neither is anything at times you stay silent over.

While recording, pitch detection is tuned to your selected harp: only sounds that harp can actually make are considered (a stray harmonic or room noise at an impossible pitch is ignored rather than snapped onto the grid), a note that flickers for only a single instant is treated as noise and removed again, and a brief detection dropout mid-note won’t split a held note in two. Detected notes are also placed slightly earlier than the moment they’re recognized, compensating for the analysis delay — plus whatever input latency you’ve calibrated on the Options page — so takes land on the beat you actually played. Two tips for cleaner takes: wear headphones if the chart has background music (otherwise the microphone hears the music too and can record its notes as yours), and the MPM pitch algorithm on the Options page is a strong choice for single-note playing.

Outside the span you actually play over, recording never deletes or replaces what’s already on the grid, so successive takes build up a chart incrementally. If the chart has background music set, it plays automatically while you record, the same as Play and Practice, so you can play along to it.

Undo and redo

The ↶ Undo / ↷ Redo buttons (or Ctrl+Z / Ctrl+Y) step back and forward through your edit history — note placement, moves, resizes, deletes, paste, and Erase/Remove all count as one step each. A whole recording take (start to Stop/Finish, pauses included) undoes as a single step too, not one step per frame the note grew. Both buttons dim when there’s nothing to undo/redo in that direction, though clicking them then is harmless either way.

Keyboard shortcuts

These work whenever you’re not typing into a text field:

Saving and loading

Save/Load work with .harpchart files directly; Browse picks the background-music audio file a chart references. Either one reports what happened right in the status bar — a green “Saved”/“Loaded”, an amber “saved with warnings” (for example, a lesson chart missing its ID), or a red failure message — not just in the log.

A saved chart is validated against Harmonicon’s chart schema (assets/song_schema.dtd.json) and tagged with the format version it was written against, so a chart saved by a newer Harmonicon that added something this version’s Song Editor doesn’t understand will point that out clearly instead of silently mis-loading.

Difficulty is a Details control with the chart format’s four choices: easy, intermediate, advanced, and expert. Song Feel separately chooses straight or shuffle metronome subdivision; its default setting leaves the player’s current choice untouched. Source and license are editable text fields in the same form; description uses a four-line word-wrapped box, where Enter starts a new line and leaving the box commits the text. Perfect, Good, and Miss Window fields edit the scoring timing in milliseconds; blank, zero, or invalid values fall back to 60, 120, and 220 ms. Combo controls set whether streak multipliers are enabled and their base, increment, maximum, and decay time. Loop controls choose its section type, repeat behavior, and inclusive start/end phrase indices; out-of-range indices are clamped to the phrases that currently exist. Style-bonus scoring rules are retained from a loaded chart.

Loading also stops before changing the open chart when a file uses musical features the grid cannot preserve yet, such as combinations of mutually exclusive technique modifiers. The status bar names the unsupported feature; the original file and the current editor contents remain untouched.

For songs you want the game to discover automatically without editing the bundled assets, drop the finished chart folder into ~/Harmonicon/songs/ (see Getting Started).

Options

Main Menu → Options holds every audio and display setting:

• Music / Metronome volume sliders.
• Input lag slider — manually nudges the same offset Calibrating Input Lag sets automatically; the results screen after a scored song also offers a one-click “apply the measured offset” shortcut if your timing consistently reads early or late.
• Microphone — a dropdown of every input device your system reports. A warning banner appears here (and nowhere else) if no working microphone is detected; see Troubleshooting.
• Harmonica model — pick which 3D harmonica model Play 3D and the Bending Trainer render, with a live rotating preview of each option.
• Pitch detect — which pitch-detection algorithm to use (FFT, YIN, pYIN, MPM, or NMF), each with a short explanation of its trade-offs shown alongside the picker. The default works well for most setups; switch algorithms here if pitch detection feels unreliable for your particular mic/harmonica combination.
• Note labels — swaps the up/down arrow on falling notes for the actual hole number, in both Play 2D and Play 3D.
• Adaptive Difficulty — off by default; turns on gradual note unlocking for every song (see Playing a Song). One setting shared by every song, not picked per song — the pause menu’s own toggle during a song changes this same setting.
• Theme — opens the theme picker.
• Calibrate input lag — opens input-lag calibration.

All Options settings persist to disk automatically and apply the moment you change them — there’s no separate “Apply” or “Save” step.

Calibrating Input Lag

Every microphone and audio setup has a slightly different delay between a sound happening and Harmonicon actually detecting it — this screen measures yours and turns it into the Input lag offset used to judge timing in every scored mode.

Options → Calibrate input lag:

1. Click to start; a metronome click plays on each of a few beats.
2. Play any note on your harmonica right on each beat — you don’t need to match a pitch, just the timing.
3. A timing bar shows each hit as it’s captured, colored green (perfect) or orange (good) by how close it landed.
4. Once enough hits are collected, the screen shows your mean offset and a suggested Input lag value.

The suggested value is also offered as a one-click apply from every song’s results screen afterward, so you don’t have to remember to come back here — if your timing consistently reads a bit early or late during real play, that’s the quicker way to fix it. Running this screen once when you first set up your mic (and again if you switch microphones or headphones) is usually enough — it isn’t something you need to redo every session.

Themes

Options → Theme lets you pick a visual theme for the menus — background images and button styling/sound effects.

Pick a theme from the list on the left; a preview appears on the right. Harmonicon ships with a couple of themes out of the box, and reads additional ones from ~/Harmonicon/themes/ the same way it reads extra songs (see Getting Started) — drop a theme folder there and it appears in this list without needing to reinstall anything.

Themes control appearance only: backgrounds, button art, and button sounds/ shader effects. Where every button actually sits on screen is always the page’s own layout, not something a theme can move around — so switching themes never rearranges a menu, only re-skins it.

Help / About

Main Menu → Help / About collects everything that isn’t about playing the game itself:

• Documentation — opens this book in your default browser, if it’s been built locally (mdbook build in docs/book/). If it isn’t found, a status message tells you so instead of failing silently.
• About — a short description of Harmonicon and the version you’re running.
• Tutorial — the guided tour of every screen. See Guided Tour.
• Credits — the people and tools behind Harmonicon.

Press Esc, or click Back, to return to the Main Menu.

Guided Tour

Main Menu → Help / About → Tutorial is a quick, hands-off tour: click it and Harmonicon automatically walks through every top-level screen — including a few seconds of live play, not just menu captions — before returning you right back to where you started:

Main → Play → Select Mode → a live Play 2D demo → Jam Session Menu → a live Jam Session demo → Generate a Jam → Bending Trainer → Lessons → Song Editor → Options → Theme → Help / About → back to where you started.

• A step counter (“Step 6 of 13”) in the overlay shows your progress through the tour.
• Menu steps switch beneath the overlay exactly as if you’d clicked through them yourself; the live-play steps actually enter that screen for real — the 2D and Jam Session demos briefly play the bundled example song, the Bending Trainer and Song Editor steps show those screens exactly as you’d see them normally. Either way, the overlay blocks clicks on whatever’s behind it — you’re not meant to interact mid-tour, just watch.
• Escape does nothing while the tour is running, on any step — including the live-play ones, where it would otherwise pause the game, back out of the Bending Trainer, or leave the Song Editor. The demo song is long enough that a live-play step never actually finishes on its own; the tour always cuts away first, and nothing from a demo step is ever saved to your profile.
• Click Skip Tutorial at any point — including during a live-play step — to end the tour immediately and return to wherever you started it from, instead of waiting for the remaining steps.

This is meant as a fast first orientation, not a substitute for the rest of this book — it covers what each screen is (and, for the live-play steps, a glimpse of what it actually looks like in motion), not how to use it in depth. For that, see the dedicated chapter for whichever screen you want to know more about (linked from The Main Menu).

Controls Reference

Harmonicon is played with your harmonica and microphone — the keyboard and mouse are only for navigating menus and controlling playback, never for playing notes.

Global

During gameplay (Play 2D / Play 3D / Jam Session)

A ⏸ button in the bottom-right corner does the same thing as Esc for pausing — no keyboard required.

Song Editor

See Song Editor for everything else — grid snap modes, multi-selection, the metronome/count-in, and more.

Menus and dialogs

The UI’s overall zoom is the Zoom slider in Options, not a keybinding — focus it and ←/→ step it, or drag it with the mouse.

Every screen can be driven from the keyboard alone. The control with focus is outlined by a focus ring, and Tab stays inside whatever modal is open — a confirmation dialog, a file picker, an open dropdown — so it can’t wander onto something you can’t see. A focused button responds to Enter and Space exactly as it does to a click.

Scrolling and touch

Any screen with more content than fits scrolls, and there are three ways to move it:

• the mouse wheel over the content,
• the scrollbar down its right-hand side (which hides itself entirely when everything already fits), or
• dragging the content itself, anywhere on it.

Dragging matters most on a touchscreen, where there’s no wheel and the scrollbar is a thin target. It works everywhere a page scrolls — song and artist lists, the options pages, the lesson tree. Starting a drag on a button doesn’t press it: a short movement is still treated as a tap, and once you’ve moved far enough to be clearly swiping, the button under your finger is let go rather than activated.

The Lessons skill tree scrolls in both directions, so dragging it pans diagonally as well.

Pause menu (mouse-driven)

The pause menu itself is buttons and sliders, not keybindings, but it’s worth knowing what’s there since it’s easy to miss mid-song. It’s two columns: transport actions on the left, practice aids on the right.

• Resume, Restart, Quit Song (left column)
• Wait for Note — freeze the highway/music at the next unhit note
• Practice Speed — a slider, 50%–100%
• A–B Loop — drag on the song-progress bar to set a loop range; Clear Loop removes it
• Adaptive Difficulty toggle; override a phrase by clicking its rectangle on the progress bar’s bottom strip, then dragging the Learned slider

See Playing a Song for what each of these actually does.

Touch

Harmonicon runs on Android, where there’s no keyboard and no mouse wheel. Every keyboard-only action has an on-screen equivalent, plus two gestures in the Song Editor:

• Drag the tool sidebar to scroll it, when the palette is taller than the screen. (A scrollbar thumb in a column that narrow is not a realistic target for a thumb.)
• Two-finger drag anywhere on the editor to pan the view — sideways through the chart, and vertically if anything is off-screen. Two fingers rather than one, because one finger is already placing, moving and resizing notes.

Switching Options → Button style to icons only makes the sidebar much narrower, which is worth doing on a phone: a landscape screen is wide and short, so spending width costs you nothing and spending height costs you the grid.

Touch is not yet verified on real hardware — it’s been exercised on an emulator only, and hit-target sizes in particular haven’t been tuned for fingers.

Troubleshooting

No microphone detected

If Options shows a warning banner instead of picking up sound:

1. Confirm your OS actually sees the microphone (check your system’s sound settings outside Harmonicon first).
2. Open Options → Microphone and try selecting a different device from the dropdown — some systems expose the same physical mic under several names (e.g. a generic “default” entry alongside the specific hardware name), and only one of them may actually be live.
3. If you plug in or unplug a mic while Harmonicon is running, revisit this dropdown afterward — the device list doesn’t always refresh itself.

Notes aren’t registering, or the wrong pitch registers

• Try a different pitch-detect algorithm (Options → Pitch detect). Different algorithms trade off differently between low-note accuracy, responsiveness, and noise tolerance — if one struggles with your particular mic/harmonica/room combination, another often won’t.
• Play closer to the microphone, and closer to the harmonica than to your mouth — breath noise close to a laptop mic is a common source of bad reads.
• Use headphones instead of speakers. Backing-track or metronome audio leaking back into the mic can be misread as a note.
• Very low-pitched harmonicas (low-keyed diatonics, the low end of a chromatic) need a detector range wide enough to cover them — this is handled automatically per-chart, but if a specific low note never registers, double check the chart’s declared harmonica key matches the harp you’re actually playing.

Timing feels consistently early or late

Run Calibrating Input Lag once — a mismatched Input Lag offset shows up as every hit reading a bit early or a bit late, even when your actual playing is on the beat. The results screen after any scored song also offers a one-click “apply the measured offset” button if you notice this without visiting the calibration screen directly.

A chart won’t load

Harmonicon checks a chart’s declared metadata.format_version against what the current build’s loader understands, and refuses to load anything declaring a version newer than that, with a clear error naming both versions — rather than failing on a confusing, unrelated error further into loading. If you see this, update Harmonicon, or double-check the chart’s format_version field wasn’t set higher than it should have been.

An older chart is a different story: Harmonicon automatically fixes up a handful of known old-format issues (like a leftover field from a since- removed feature) the moment it loads the file, so an old chart just works without you needing to edit it by hand. This happens silently in memory — it doesn’t rewrite the file on disk — unless you also save it again from the Song Editor, at which point the fixed-up version is what gets written.

The game feels stuttery or slow

• Practice Speed (pause menu, 50%–100%) slows the highway/metronome down without pitch-shifting audio — useful for a genuinely hard passage, but won’t fix an actual performance problem.
• Play 3D renders more than Play 2D; if performance is the issue rather than difficulty, try Play 2D instead.