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

The first launch

Harmonicon’s lessons and songs are not part of the download: they live in their own online repositories, so they can grow without waiting for a new version of the game. The first time it starts, Harmonicon fetches them — only their latest version, so it stays small — and shows Getting lessons and songs until they arrive. This needs an internet connection once; if it fails, the screen says why and offers Retry. After that the game starts straight away, and never updates them without asking you.

The first time Harmonicon starts — before it has saved a profile — it opens on a welcome page instead of the main menu, with the three things worth doing before anything else: Set up your microphone (the Options page, with the device picker and the “no microphone” warning), Take the guided tour, and Start with a lesson. Each one brings you back here when you’re done, with a check beside it, so you can take the next; Skip for now goes straight to the main menu. You can come back to this page any time from Help → First-time setup.

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 another source of songs, lessons and themes, alongside the ones it downloads — 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/ note art folder — 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. (A 3d/ folder is accepted but no longer used: Play 3D draws every note as a ribbon.)

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, and microphone settings. See Options.
• Help — documentation, information about the app, the guided tour, and credits. See Help.
• 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 Song — browse all downloaded songs and anything you’ve added to ~/Harmonicon/songs/ (see Getting Started). Click a column header to sort by song name, band, genre, difficulty, your rating, mastery, or times played; click it again to reverse the order. Search accepts partial words and small typos.
2. Choose 2d or 3d with the switch beside Play. Play 2D uses a scrolling note highway; Play 3D puts the same notes on a lane in perspective. Both share scoring, timing, and the pause menu.
3. Click a song once or use Up/Down to select it and inspect its details. Click Play to start the selected song. / focuses Search; Clear resets the search. Moving the pointer over other songs keeps your selection.
4. Confirm the physical harmonica you are holding. A 3-2-1 countdown then shows the song title and key before the chart and backing track start.

Select a song, then click its My rating stars to set the rating directly. The left half of a star chooses a half-star step; the right half chooses a full star. Click the current rating again to clear it to zero. Ratings range from zero to five stars in half-star steps (stored as 0–10). Mastery shows the accuracy from your latest completed gameplay, even when it is lower than an earlier result. — means no result has been recorded. Filter mastery cycles through all songs, unplayed songs, below 50%, 50–79%, and 80–100%; it combines with Search. Ratings and latest results are saved across restarts, separately for each song source. Times played counts completed song runs, including previously saved plays; click its column header to sort by the count.

When a repository check finds newer songs, an Update songs button appears above the catalog. Confirm it to download that repository’s latest version; the catalog refreshes when the download finishes. If a download fails, the existing songs remain available and you can retry the update. Checks are available in Options → Lessons & songs.

Removed and hidden songs

Updates keep your local copy of songs removed from a repository, including backing tracks. Select one to see Kept locally — no longer in … and its source repository. If it returns to that repository, the latest copy replaces the retained version and the warning disappears. Each repository keeps its own copies independently.

Delete song hides the selected song from that source after confirmation; it keeps the files. Hidden songs stay hidden across updates and restarts, even if their chart filename changes. A copy from another repository remains visible. Exclusions are stored in hidden-songs.json beside settings.json. To restore a hidden song, remove its entry from that file while the game is closed.

Pickups and repeats

Some tunes start before the first full bar — the “and a” before bar 1. The game counts those opening notes as the end of an extra bar, the way a musician would: the metronome accents bar 1’s downbeat rather than the first note, and the beat guides and notation staff line up with it.

A song written with repeat signs plays them out in full. A repeated passage comes round again, first- and second-time endings are taken on the right pass, and every note of every pass is scored.

Lyrics

A song with words shows them karaoke-style under the notation staff: the current line lights up syllable by syllable as each one’s note is played, and the next line waits dimmed below it so you can read ahead. Songs without lyrics show nothing there.

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.
• Every note is a ribbon as long as the note lasts, in both Play 2D and Play 3D. Its bright front edge is the attack — play when it reaches the hit line — and the technique is drawn along it: a vibrato is a wavy line and a wah pinches the ribbon in and out, both spaced so each swing crosses the hit line at the rate the chart asks for (follow the ribbon and you’re wobbling at the right speed); a bend steps the ribbon’s bright core sideways, further for a deeper bend.
• Each technique note says what it wants. The note’s tab carries the bend depth — one ' per half step, so -3'' is draw 3 bent a whole step — and a short label beside the note gives the note to land on (→ A) or the wobble rate to play (vib 5/s: five swings a second).
• A coach bar at the end of the track guides the technique as you play it. It sits between the highway and the hole strip, never moves, and uses large type. For a bend it runs from the unbent note on the left to the target on the right, with the target band in green; the marker is your pitch, so bending slides it right, and it turns green once you’re there (Bend more / Hold it / Too far). For vibrato or wah, a pale tick swings at the rate the chart asks for — copy it — and once you’re holding the note your own pitch (vibrato) or volume (wah) swings beside it, with Faster, Slower, Wider or Good at the end, judged exactly as the score is. Songs without bends, vibrato or wah don’t show the bar.
• 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.

Every judgment shows on the note itself, not just in the readout by the hit line: a hit note’s ribbon widens for a moment and turns gold, its tab becoming a ✓; a missed one narrows, dims to red and gets a ✗ — so hit and miss are told apart by shape as well as colour. While you hold a long note, the part of its ribbon still above the line stays gold as long as the right pitch is sounding and goes grey the moment it drops out; on a vibrato or wah note the gold shimmers once the wobble is heard at the right rate, before the hold ends, so you can correct it in time.

A combo multiplier builds on consecutive hits and resets on a miss. The Results screen after each song is written as coaching, not just a scoreboard:

• Accuracy leads, with one observation under it — the single most useful thing the run showed: a technique that trailed your plain notes, too many notes that never sounded, hits that consistently came in late or early, or attacks with a neighbouring hole leaking. It only says something it has evidence for — one attempted bend is never “your bends need work” — and says “nothing stands out” when a run is solid.
• Timing as a distribution, not an average: an early / on-time / late bar with the counts. The one-click Input lag adjustment (see Calibrating Input Lag) appears only when your hits actually lean one way, since a wide scatter can average to a number without any lag being the cause.
• By technique, ranked by where practice would pay off most, always with the sample counts alongside.
• Practice missed section loops the two bars where you missed the most, using the same A–B loop the pause menu offers, and starts you there rather than from the top of the song. Leave it with Esc → Quit Song, or clear the loop from the pause menu to carry on through the rest.

For a lesson, the pass/fail verdict and how far you got toward its goal sit above all of that.

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 ribbon as long as the note lasts, scrolling down toward a fixed hit line. The bright cap at a ribbon’s bottom is the attack, and holds the note’s tab (-4, -3'' for a bend).

• Notes are colored by breath direction — blow and draw each get their own color, shown in the legend beside the highway.
• A note turns gold while you hold it, and red if it’s missed. Techniques are drawn along the ribbon — see Playing a Song.
• 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 in each note’s cap 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 as a lane seen in perspective, with notes travelling toward you.

• One lane per hole, with a row of hole pads at the near end: a pad glows blue or orange when you play that hole, and dimly when a note in its lane is due. The bright line across the lane is the moment to play.
• The camera looks down the lane steeply enough that notes keep a steady pace all the way in, rather than crawling in the distance and rushing the last stretch.
• Each note is a ribbon lying on its lane, as long as the note lasts. Its bright front edge is the attack — play when it reaches the line — and a small gap at its end keeps two notes on one hole apart.
• The technique is drawn along the ribbon. A vibrato is a wavy line and a wah pinches the ribbon in and out, both spaced so each swing crosses the hit line at the rate the chart asks for: follow the ribbon and you’re wobbling at the right speed. A bend steps the ribbon’s bright core sideways, further for a deeper bend.
• While you hold a note its ribbon turns gold, and greys the moment the pitch drops; a hit widens it briefly and a miss narrows it and dims it red.
• Beside each ribbon’s front edge, a label gives its tab — including bend marks, -2' — and, for a technique note, what it asks for (→ F#, vib 4/s). Plain notes get a label only with Options → Note labels on.
• The same technique coach bar as Play 2D sits along the bottom on songs with bends, vibrato or wah (see Playing a Song).

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 the chosen backing and Loop setting allow. Nothing is scored.

By default the screen is a calm stage with one visual centre: the song title and which harp to grab, the Loop toggle (restarts the backing track when it ends, instead of stopping), the chorus/bar position, a big current → next chord readout, a compact twelve-cell form strip that lights the bar you’re in, and one line naming the hole and breath the mic hears — gold for a chord tone of the bar currently sounding, green for anywhere else in the blues scale, amber for outside it. Follow the colour, not memorized theory. That’s everything you need to keep your eyes off the screen for a whole chorus.

Click Guides to open the rest, remembered between jams:

• Left: the full 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 that recolors each hole/direction as you play, in the same colours as the indicator.

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. Generated jams continue automatically and replace the finite-song Loop control with End after this chorus.

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

Call & Response

Turn on ⇄ Call & Response and the game takes turns with you: every four bars it plays a short harmonica phrase over the chords that are sounding — two bars of “Listen…” — then steps back for two bars of “Your turn”. Answer however you like: echo it, vary it, or play something else entirely. Nothing is compared or scored; the hole map just shows the call’s holes in a soft violet until the next one, as a reminder of where it went, and lights whatever you play in the usual colours.

The phrases are made for the harmonica you’re holding, using only plain blow and draw notes, so a call never asks for a bend you can’t reach. Each one has a little shape to it — a short motif, some space, an answer that repeats or moves it up or down — and always lands on a chord tone with a breath of air before your turn. The backing dips slightly while the call speaks so it’s easy to hear.

Phrasing cycles how busy the calls are: sparse (a few long notes, lots of room), conversational (the default) or busy (eighth-note runs). It’s a mood, not a difficulty level — pick whichever you’d rather trade phrases with.

The band listens

In a generated jam the rhythm section pays a little attention to you. It never judges a note — it only notices how much you’re playing and when you stop:

• After a busy four bars, the comping thins out for the next four so there’s more room under you; play sparsely and it fills back in.
• Play a phrase and rest in the last bar of a four-bar stretch, and the band may answer — a short drum fill or a chord push into the next downbeat. It does this now and then, not every time.
• Stop playing altogether and it simply holds the groove; it won’t rush to fill the gap.

Everything changes at bar lines and eases in, so a noisy mic can’t make the band twitch. Adaptive band turns it off if you’d rather the backing play exactly as generated.

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 rhythm section on the spot, with separate bass, drum, and chordal-comping stems, so you can jam without needing any existing content.

The band marks the ends of each four-bar phrase with short drum pickups and uses the final bar for a bass-and-drum turnaround into the next chorus. These variations leave the next downbeat and the harmonica register clear. Across four choruses, the arrangement grows from a sparse opening to a fuller third chorus, then relaxes before beginning the arc again. Small timing and touch differences keep the players from landing like one machine, while the downbeats and bar lengths remain locked together. Restart replays the same performance; starting a new jam creates a fresh variation. Use Band energy to make that arc quieter and roomier or denser and more assertive. It changes accompaniment density and dynamics without changing the tempo or chord progression.

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).
• Band energy — Low, Medium, or High accompaniment density and dynamics. It does not alter tempo or harmony.
• 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).
• Scale — the note palette used by the live hole guide.
• Genre — Blues, Jazz, Rock, Reggae, or Country. Each changes the bass pattern, drum pocket, comping rhythm, and instrument tone.
• 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 — the same calm form display and optional Guides, just with a generated backing instead of a real song’s. It keeps playing across backing-buffer boundaries automatically; the chorus/bar readout remains continuous. Choose End after this chorus to stop at the next 12-bar boundary with a two-beat tonic hit from the whole rhythm section. Muted stems stay muted for that ending. Restart returns to the count-in and chorus 1; Quit Song returns to this setup page (with your setup choices remembered), not the song list, since there was never a song list involved. The stem buttons let you mute Bass, Drums, or Comping independently without disturbing the timing of the others.

Bending Trainer

Play → Bending Trainer is a practice screen for controlling one bend at a time: no song, just the hole you’re working on, a live picture of your pitch, and the harmonica’s full bend diagram. It’s a tool for finding, holding and releasing a bend, not a lesson, so it never grades you pass or fail.

The screen has three parts:

• A strip across the top for the things you set once and leave: Setup (your harp’s key and the pitch detector, summarised as e.g. C harp · FFT), Scope and Practice (below), the metronome with its tempo buttons, and Advanced.
• The target card, the large panel at the centre. It shows what you’re practising and how close you are, with every button the current attempt needs.
• The harmonica diagram, beside the card on a wide screen and below it when a tablet is held upright. The layout follows the tablet as you turn it.

Setup and Advanced open as panels that float over the screen, so opening one never moves the pitch display you’re watching. Press the same button again to close it.

Picking a target

Click any cell in the diagram to make it the target. You can also press Tab to focus the diagram, move around it with the arrow keys, and press Enter or Space to choose a cell. The target card names the hole and technique, and says how it has gone for you so far (Not practised yet, or e.g. 7 of 10 controlled).

Natural plays the hole’s unbent note and Target plays the note you’re aiming for, as clean reference tones, so you can hear the interval before you try to bend it. Check natural note is an optional first step: it asks for the unbent note on that hole, which confirms the microphone is following the right hole. It also measures where that reed actually sits on your harp, since real reeds rarely match the textbook tuning exactly. From then on, that hole is judged against your harp rather than the table.

Reading the pitch rail

The tuner line reports how far you are from the target and in which direction. It only does so for notes that belong to the selected hole: silence, the wrong hole and an unsteady signal each get their own message instead of a misleading number.

Below it, the rail runs from the natural note on the left to the target band on the right. The bright marker is your pitch right now, and the fading dots behind it are the last few seconds of movement. From them you can see a smooth approach, a scoop, an overshoot past the target, or a pitch that settled. When a hole has several bend depths, the shallower ones are marked along the way to a deeper target. Three separate readouts sit under the rail: distance from the target, how steady the pitch is, and how long you’ve held it centred.

Practice and the drill

Practice chooses what counts as one success. Free exploration adds nothing. The other shapes ask you to find and hold the target, bend and come back to the natural note, repeat the bend on metronome beats, climb through the bend depths and back, or attack and release an overbend. The status next to the button shows which stage you’re at.

Scope chooses which targets the drill uses: First bends (holes 2 and 3 draw bends, the default), All bends, Blow bends, Overbends, or Custom. With Custom selected, clicking diagram cells adds them to the drill or takes them out again.

Turn on Drill and Harmonicon picks targets for you from that scope. It favours ones you haven’t tried, ones you control less reliably or less steadily, and ones you haven’t practised for a while. It moves on when you complete the chosen practice shape. Skip moves on straight away. Neither Skip nor putting the harp down counts against you: an attempt only counts once the microphone has heard you play that hole. Your record is saved between sessions.

The diagram doubles as a progress map. Each cell is tinted by how often you control it, and a bar along its bottom edge grows with the same number, so you can read your progress without telling red from green. Cells you’ve never tried have no bar.

Advanced

Advanced is for precision work, and you can ignore it entirely. It sets the tolerance, how long a hold must last, how long an attempt may take, the A4 reference pitch, how much pitch history the rail shows and how much it’s smoothed, and how many pulses per beat the Repeated shape asks for. Its This attempt section shows your mean distance from the target, how widely the pitch wandered, your best hold, and your vibrato’s speed and width. It also shows the measured reed centre from Check natural note, with Forget measured reed to discard it. Reset puts every setting back. These readings describe the pitch and nothing else: the trainer makes no claims about breath, embouchure or the health of your reeds, because a microphone can’t tell.

Leaving

There’s no pause menu here, because there’s no song to pause. Click Back in the header, or press Esc, to return to the Play menu. 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 core unit stays shut until you’ve passed most of the one before it (elective units don’t — see below); 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. Above the tree, each skill with ladders gets a mastery meter (“Bending — 40%”): how many of its ladders’ tiers you’ve cleared. It only grows when you pass a tier, never just for time spent, and a failed retry never takes anything away.

Passed tiers come back for review at widening intervals: the day after you first pass one, then two days after a successful review, then four, eight and so on, up to about two months. When some are due, a Warm-up row appears above the tree with up to three of them — each lesson at the hardest tier you’ve passed — and clicking one starts it straight away. Every lesson with a review due also shows a gold ↻ beside its node, so you can see them all, not just the three in the row. Missing a review never costs you the tier, and the dots and meters never go down; it just brings the review round again sooner.

Every day you finish a song, lesson or training counts as a practice day, and once you’ve practised two days running the tree shows your practice streak (“5-day practice streak”). Missing a single day doesn’t break it. Missing more simply starts a new one next time — nothing is taken away, and there’s no reminder nagging you about it. 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.

The tiers sit in a row under their names — Isolate, Consolidate, Vary, In Context, Interleave — with a ✓ on the ones you’ve passed. Picking one shows what it asks of you and exactly what counts as passing it, such as “Goal: 70% accuracy on bend notes, at 96 BPM for 4 bars”, before you press Start Training. The row opens on the first tier you haven’t passed yet, but none of them is locked: practise them in any order.

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’re open from the start: each elective lesson unlocks as soon as its own prerequisites are passed, wherever you are in the core course, so there’s almost always something besides the next core lesson to choose.

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/Meter tools, the Repeat and Ending buttons, 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, with a notation staff below it showing the same notes as sheet music. The staff follows the grid as you scroll (and the playhead while playing), and the notes you select are drawn in gold on it too, so you can see where the selection sits in the music.
• 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. The technique buttons act on the whole selection too: the last note you clicked decides the value (the next bend depth, vibrato rate or depth step), and every selected note that can play it takes it. Notes that can’t, such as an overblow on hole 2, keep what they had, and the status bar says how many. Use Transpose up (♯) or Transpose down (♭) to move the selection by one semitone; with no selection, they transpose the whole chart. Harmonicon recomputes the hole, breath, and technique on the current harp and leaves a note unchanged when the destination is unplayable or occupied.
• 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, Groove and Lyric 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 four fields (see Lyrics for the last one) — 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, Groove and Lyric 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.

Lyrics

A song’s words go in the Lyric field of that panel, one syllable per onset: the syllable sung when those notes start. In the game they appear karaoke-style above the notes, lighting up as each syllable’s note is played. Two marks shape the lines:

• end a syllable with - when the word carries on (A- maz- ing reads “Amazing”);
• start one with / to begin a new line (/I once was …). Without one, a long line wraps between words by itself.

To type a whole line at once, enter its syllables separated by spaces: they land one per onset from the phrase you opened onwards, replacing what was there. Use _ for an onset that carries no syllable, such as a note held over from the word before. A single word just sets that one phrase, and an empty box clears it. The marker in the header shows the syllable in quotes.

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.

Pickups

A tune that starts before the first full bar — the “and a” before bar 1 — has a pickup. Type its length into Pickup (beats) in Details, in beats of the opening time signature: 1 for one beat, 0.5 for a single eighth note in 4/4. Leave it blank for a tune that starts on the downbeat.

The grid then counts the opening notes as the end of an unnumbered bar: a one-beat pickup in 4/4 is labelled beat 4, bar 1 starts right after it, and the metronome accents bar 1 rather than the first note. Every later bar number, the 12-bar tint and the notation staff follow, and in play the beat guides and the metronome count the same way. Importing a MIDI file clears the pickup, since MIDI doesn’t record one.

Repeats and endings

A passage that is played twice only needs writing once. Select its bars on the ruler with the Select tool, then press Repeat: the selection snaps to the nearest bar lines, and the ruler marks the start with ‖: and the repeat sign with :‖ ×2. Press Repeat again on the same bars to play them three or four times; once more removes the repeat.

For first- and second-time bars, select the bars that differ and press Ending. Bars inside the repeated passage become the first ending, played every time but the last. Bars starting right at the repeat sign become the second ending, played only on the last time through. Press Ending again on the same bars to remove one.

The editor shows and plays the song as written, once through. When the song is played in the game the repeats are played out in full: every pass is scored, and a backing track should be a recording of the whole performance.

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’s left column 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. A repeat or ending inside the removed range is removed with it, and later ones move back with their notes. 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).

Saving over an existing file asks for confirmation. Chart, lesson, and backing files are written through temporary files before replacement. If a lesson’s chart or a MIDI backing file cannot be written, the status bar reports a save failure. A save involving several files is not a single transaction: some companion files may already have been replaced when a later write fails.

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.
• 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.
• Fullscreen — borderless fullscreen on the current display.
• Colorblind Palette — a fixed colorblind-safe blow/draw colour pair on the highway instead of the current theme’s note colours.
• Reduced Motion — stills the decorative motion on the highway: the pop when a note is hit, the flowing animation on note tails and the shimmer on a held note. Notes keep scrolling as usual (that is the game), a missed note still shrinks — just immediately, without the movement into it — and the hit line never moves either way. On the skill tree, opening or closing a unit snaps straight to the new layout instead of animating.
• Zoom — scales the whole interface.
• Theme — opens the theme picker.
• Lessons & songs — where your lessons and songs come from, and their updates: see Lessons & Songs.
• 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.

Lessons & Songs

Harmonicon’s lessons and songs don’t come inside the game: they live in online git repositories, so new lessons and songs can arrive without a new version of the game. Options → Lessons & songs shows where yours come from and keeps them up to date.

The page has a list for songs and a list for lessons. Each repository shows its name, its address, and how it stands:

• Version …, up to date — nothing newer is published.
• Version …, an update is available — an Update button appears. Harmonicon never updates on its own; it asks first, and only downloads the newest version, not the whole history.
• Checking for updates — Harmonicon asks each repository when the game starts, and again whenever you press Check for updates. Asking downloads nothing.
• Not downloaded or Could not download — press Download to try again (an internet connection is needed).
• Can’t be used — usually because the repository needs a newer Harmonicon. Update the game, or remove the repository.
• A folder on this computer — see below; it is read as it is, with nothing to update.

Remove takes a repository off the list and deletes what was downloaded for it. Your progress is kept: if you add the same lessons back later, the ones you passed are still passed.

Adding a repository

Anyone can publish lessons or songs: a git repository laid out like Harmonicon’s own (harmonicon-lessons, harmonicon-songs; each has a README describing its layout) works on GitHub, GitLab or any other git host. Type its address — https://… or git@host:owner/name — into the box under Songs or Lessons and press Add. Harmonicon downloads it straight away and its songs or lessons appear alongside the others.

You can also type a folder on this computer. Harmonicon reads it in place and never changes it, which is how lesson and song authors try their work before publishing it: edit the files, and the game picks the changes up.

Lessons and songs are only data — charts, text and pictures, never programs — but add only repositories from people you trust.

The first start

The first time Harmonicon starts, it downloads its lessons and songs before opening the menu (see Getting Started). You can leave downloads running with Continue without missing packs. If a download fails, Retry tries again. Continue without missing packs opens the menu with whatever content is already available. You can then open Options → Lessons & songs to retry downloads or add a local folder.

If you remove every repository, the game still starts; it just has no lessons or songs until you add some.

Song updates preserve songs removed upstream. The song picker labels those local copies with their original repository. Delete song in the picker hides a song persistently from that source, including after future updates; a copy supplied by another repository stays visible. See Removed and hidden songs.

Help

Main Menu → Help 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.
• Tutorial — the guided tour of every screen. See Guided Tour.
• First-time setup — re-opens the welcome page a fresh install starts on: microphone setup, the guided tour and a first lesson, each returning you there when done (see Getting Started).
• Credits — the people and tools behind Harmonicon.

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

Guided Tour

Main Menu → Help → 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 → 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.

In the song picker, the active column header has a highlighted background and a direction arrow; click it again to reverse the order. Sorting keeps the selected song in view. The current song has a bright border. Use Up/Down to move through songs, Home/End to jump to the first/last song, and Enter or Space to start the focused song. Tab and Shift+Tab move between sorting, search, view mode, and songs. Typing in Search filters the list without moving focus away from the field. Search matches partial words in song names, bands, and genres; multiple words can match across those fields. Words of 4–7 characters allow one typo, and longer words allow two, using Levenshtein distance.

The picker shows a result count and a selected-song preview. Hover a song to preview its details without leaving Search. Clear resets search and keeps the field focused; / focuses Search when you are outside a text field. The two-position 2d / 3d switch beside Play shows the active view with a filled background and remembers your choice when you reopen Play Song. Play starts the selected song and is disabled when no songs match.

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.