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 12-bar chord grid, metronome, technique legend, and score/combo all sit in the HUD to the side of the highway.
• 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, grouped into units shown as tabs across the top, with a scrollable list of that unit’s lessons below.

Lessons unlock in order: each one lists its prerequisite(s), and shows locked (🔒, dimmed, not clickable) until you’ve passed them. A passed lesson gets a ✓ and stays replayable any time. Your progress is saved (profile.json) and survives restarting the game.

Clicking an unlocked lesson opens its reader page: instructional text explaining the technique, a goal line (e.g. “Goal: 70% overall accuracy”), and a Start Lesson button (or Mark as Done, for the couple of lessons that are pure instruction with no drill — like tongue blocking, which the microphone genuinely can’t tell apart from puckering, so it isn’t scored).

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 three 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, and — the last lesson — leave real space, playing two bars and resting two bars through the whole form. All three use the same “Finish Lesson” pause-menu flow as Unit 2’s improvisation lesson.

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, holding every action: Back, the mode buttons, undo/redo, the note techniques, and Save/Load. It 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; 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 tool sidebar sets the selected note’s technique: Blow/Draw direction, bend depth, overblow/overdraw, slide (chromatic only), wah/vibrato 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 (diatonic/chromatic, and hole layout), background music file, and song name/author — everything under song and harmonica in the .harpchart format.

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.

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. 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 to match. 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.

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

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.