Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

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 ignored.)

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).
  • Note Trainer — isolated technique practice for your instrument: the harmonica’s Bending Trainer, or the Note Trainer for the guitar or the flute.
  • 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, instrument, genre, difficulty, your rating, mastery, or times played; click it again to reverse the order. The Instrument column says whether a song is a harmonica, guitar or flute part. A guitar or flute part also says how much of it your own instrument can play, from the tuning, capo and foot joint in My instruments: “Guitar · 83%” with a capo that puts the low notes out of reach. It counts note by note; the page before the song gives the exact count. Search accepts partial words and small typos, and matches the instrument too.
  2. 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.
  3. Say what you are holding: the harmonica’s key and type for a harmonica part, the tuning for a guitar part, the foot joint for a flute part (see below). 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.

Guitar parts

A song folder can contain several charts. Select the part from the song list: filenames distinguish entries such as Duet — harmonica and Duet — guitar. Each part uses the same folder’s backing audio and background. Ratings, play history, adaptive progress and hiding currently apply to the song as a whole; separate progress per part is still planned.

Guitar charts use a horizontal tablature highway: strings run from high to low, notes approach from the right, and each note shows its fret number. A b marks a bend; angle brackets mark a natural harmonic. Scoring checks the sounding pitch, so an equivalent fingering sounds the same to the game.

For imported scores, the part picker offers guitar arrangements alongside harmonica arrangements and names the instrument beside each part. Guitar Pro tabs retain their tuning and string/fret positions. The Song Editor opens native guitar charts on its grid, one row per string. The fretboard strip beside the highway highlights the target frets and hand window.

Before a guitar part starts, Your guitar asks for your tuning: standard, drop D, half a step down, DADGAD, open G or open D, or As written. It opens on the tuning in My instruments, or the chart’s own if you haven’t named one there, and your answer is remembered for the next guitar part. Pick another and the notes stay the same pitches but move to the frets your tuning plays them on; the page says how many move. A bend keeps its bend; a natural harmonic, whose pitch depends on the open string, is played as the fretted note it sounded.

Capo works the same way: say which fret yours is on, or No capo, and it is remembered too. Frets then count from the capo, as tab for a capoed guitar does, and the line under the highway says so (“0 = the capo, at fret 2”). A note lower than your capoed strings can reach is shown but doesn’t count.

Flute parts

A flute part’s highway has one row per note the song uses, highest at the top, each named at the hit line, and every note carries its name as it travels in from the right.

Under the highway, a fingering chart shows how to play the note that’s coming. It is drawn the way a printed chart is, lying along the screen with the head joint at the left: the six finger holes in a line on the tube, left hand then a gap then right hand. The thumb key sits below the first hole, and the G♯ key, the two trill keys and the right little finger’s E♭ and foot keys sit small above the line. The keys to press are filled in, with the note’s name before the chart. The bar under it fills as the note approaches, turns gold when the note starts, and empties as you hold it. The keys turn gold too while the game hears the note. To the right, a smaller, dimmer chart shows the note after it, so your fingers can get there in time. The staff at the top marks the same note in gold.

Before a flute part starts, Your flute asks for its foot joint: a C foot goes down to C4, a B foot to B3. It opens on the one in My instruments, or the chart’s own until you’ve picked one, and your answer is remembered. A note below your foot (a B3 on a C foot) is still shown but doesn’t count, and the page says how many there are.

To hide the fingering chart, pause and press Fingering chart; the highway takes its space. Press it again to bring it back. Your choice is kept for later songs and sessions; Options sets it too.

A note’s fingering is a suggestion, as on every instrument: the game hears only the pitch, so an alternate fingering that sounds the same note scores the same. A chart may ask for a particular alternate, and the fingering chart then shows that one. Flute charts open in the Song Editor; see Flute charts.

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. 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.
  • Sections — while paused, the song’s score is shown with its sections marked above it. Click a section to select it; the two aids below act on whichever one is selected.
  • Phrase coverage — 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. Its slider sets how much of the selected section is revealed, and the pause menu’s own toggle switches the feature off or on immediately, mid-song (this also updates the Options-menu setting).
  • Repeat section — loops the selected section, for drilling one phrase repeatedly. Resume to practise it; toggle it again to stop looping.

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.

For scoring, pausing, looping and adaptive difficulty, see Playing a Song.

Guitar fingering guide

The full-neck guide above the guitar highway labels playable fretted targets with suggested fingers: 1 index, 2 middle, 3 ring, 4 little finger, and 0 for an open string. Common open chords use their usual fingerings; other targets use the current four-fret hand position where possible. These are suggestions, not finger assignments authored in the chart. Shapes without a safe suggestion retain their target dots without a number.

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.

You can jam on any instrument a song has a part for: the picker lists each part separately — Ode to Joy — chart for the harmonica, Ode to Joy — guitar, Ode to Joy — flute — and the screen draws the instrument you picked.

By default the screen is a calm stage with one visual centre: the song title (and, on a harmonica, 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 what the mic hears — the hole and breath on a harmonica, the note name (say Note G4) on any other instrument. It’s gold for a chord tone of the bar currently sounding, green for anywhere else in the 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 — your instrument, with every note that fits the scale in green and the rest grey. The note you’re playing lights up in the same colours as the indicator.
    • Harmonica: a reference bend diagram for every hole, plus the hole map, one cell per hole and breath.
    • Guitar, bass, cavaquinho: the fretboard, each string from open to the 12th fret, in your tuning.
    • Piano: a three-octave keyboard, C3 to C6.
    • Flute, clarinet, violin, viola: the instrument’s range as a grid of notes, one octave per row with the highest on top.

There’s no “wrong note” here in the scored sense — the 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

On a harmonica part, 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 instrument, 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.

Note Trainer

Play → Note Trainer asks which instrument you’re practising. Harmonica opens the Bending Trainer; Guitar, Bass, Flute, and Piano open the Note Trainer described here. Like the Bending Trainer it is practice, not a lesson: there is no song and nothing to fail.

The tabs across the top choose what to drill:

  • Notes: a string and a fret; play that note and hold it.
  • Bends: a fretted note to bend up a half step or a whole step. The status line follows the bend as it rises, so you can hear and see how far you have to go.
  • Harmonics: touch the string lightly over the fret shown, without pressing it down, to sound its natural harmonic.
  • Positions: a note and a string, but no fret. The same pitch exists elsewhere on the neck; the drill is finding it on this string.

The large line says what to play, and the line under it what the trainer hears: the starting note, how far through a bend you are, how many cents sharp or flat you sit, or which other note you played instead. Hold the note in tune until the bar fills and the drill is landed; the next one follows on its own. ‹ Previous and Next › move through the drills yourself, and Listen plays the target on a plucked string.

Single-note exercise tabs keep their own saved progress, separately for guitar, flute and piano: how many drills you’ve landed, and which drill you were on. Coming back, even after closing the game, picks up there.

The full fretboard shows every physical fret, with string 1 at the top, and marks the target on its string. A shaded region suggests the hand’s position. The target dot uses suggested finger numbers (0 for an open string), matching the song-play guide. Positions hides the target fret until Show position is pressed; the next drill hides it again. How close counts as in tune, and how long to hold, come from the same settings as the Bending Trainer’s.

The trainer hears a pitch, not a string, so in Positions it trusts you to play the note on the string it asks for.

Flute

Choose Flute foot joint above the exercise: C foot starts at C4, while B foot includes B3. This is remembered in My instruments and used the next time you open the trainer. Changing it updates both the score and the fingering drawing, keeping your current note when possible.

The flute’s tabs are:

  • Notes: every note from the lowest to C7; play it and hold it.
  • Octaves: finger the lower note, then blow faster to jump to the note above on the very same keys, the way the flute’s second octave sits on its first.
  • Alternate fingerings: a high note on one particular fingering, the standard one or one of its alternates.

The horizontal flute below lights the keys of the fingering to use, with the headjoint at the left. Filled keys are pressed; outlines stay open. Choose a note directly on the score: each note and its name form one clickable target, also reachable with Tab and Enter. The score covers the flute’s full range, including low B when using a B foot joint. Gold marks the selected target; a white outline marks the starting note for an octave drill. Dimmed notes are unavailable in the current exercise. Selecting a note keeps it for repeated attempts; enable Auto-advance to work through the sequence instead. Use Previous and Next to step through alternate fingerings of the same pitch. Listen plays the note in the game’s flute voice. As with the guitar, the trainer hears the pitch, so it trusts you to use the fingering it shows.

Piano

The trainer shows all 88 keys from A0 to C8 at a stable width. Gold marks the target and blue the detected note. The grand staff shows both clefs. Labelled left- and right-hand rectangles suggest five-finger positions, keeping a position until the target requires a move. These are suggestions, not required hand assignments: pitch detection cannot tell which hand played. The drills cover C3–C6. Listen uses the piano voice. On short screens, scroll to reach the keyboard.

Choosing and repeating a guitar target

Use Choose note to pick a pitch, then String / fret to choose one of its available positions. You can also click directly on a string and fret. The controls follow the selected exercise tab, so harmonic positions and bend targets stay playable. Choosing a target switches Auto-advance off: practise it until you choose another. After a successful hold, release the note before trying again. Turn Auto-advance on for the guided sequence. The instructions and score sit together above the full-width fretboard.

In Bends, the note picker chooses the starting pitch. Choose its string and fret, then the half- or whole-step interval. Establish the unbent note briefly before bending; hitting the final pitch alone does not complete the exercise. The live trace rises with pitch and shows a green target band. Overshoot feedback asks you to relax the bend. Release between focused attempts.

Guitar chords

In standard tuning, Chords offers Em, E, Am, A, D, Dm, C and G. Choose a chord from the combobox. Its diagram marks open strings with ○, muted strings with ×, and fretting fingers with 1–4; the full fretboard and staff show the same shape and sounding pitches. Listen plays the whole chord.

Strum the unmuted strings together and hold until the bar fills. Feedback names missing and unexpected pitches. Notes plucked one at a time cannot accumulate into a completed chord. Stop the strings ringing between attempts. The count reports successful strums this session, not mastery. Auto-advance can cycle the chord list; leave it off to repeat one chord.

A polyphonic detector is required. If a monophonic detector is selected, the trainer explains why it cannot assess the chord and offers Use chord detection (NMF). The microphone checks pitches, not which finger or physical string produced them; use the diagram to check your hand and muted strings.

Guitar opens with Auto-advance off and preserves that choice across exercise tabs. Reference playback temporarily pauses assessment so hearing the app’s own reference through the microphone cannot complete an attempt.

Bass

Choose Bass for fretted electric bass. It shares the clickable fretboard and pitch/position selectors with Guitar, with separate saved progress. The tabs offer notes, natural harmonics and alternate string positions; guitar chord shapes and guitar bend drills are not offered.

Markers show fret numbers, with 0 meaning an open string. They do not prescribe a one-finger-per-fret stretch. Use a comfortable hand position and shift as needed. The microphone checks sounding pitch, not the string or finger used.

The score uses bass clef with an octave-below indication: the written notes sit an octave above their sounding pitch. High-register targets use treble clef with the same octave relationship to keep them readable. Note names and audition audio use the sounding pitch. Standard four-, five- and six-string tunings and Drop D are available under Options → My instruments → Bass tuning. This tuning is saved separately from Guitar’s and is used when opening the bass trainer. Use a clean microphone or pickup input and mute unused strings.

Cavaquinho

Cavaquinho shares the clickable fretboard, note selector and position exercises. Its default setup is the Brazilian traditional tuning, with sounding pitches D4–G4–B4–D5 from string 4 to string 1. The preset labels list string 1 first, matching the editor and tablature. Brazilian natural and Violin / mandolin are separate presets under Options → My instruments → Cavaquinho tuning. These names describe particular traditions, not a universal cavaquinho tuning. Other tunings can be authored per string in the Song Editor.

In Brazilian traditional tuning with no capo, Chords offers G, C, D and Em shapes on four strings. The small chord diagram suggests finger numbers; the large fretboard marks fret numbers. Shapes are offered only for the tuning they were defined for. Chord assessment requires a polyphonic detector; the microphone checks pitches, not the fingering, strumming gesture or number of physical strings.

The open-string frequencies follow UFERSA’s acoustics study, table 6. The named tuning variants follow Musixe’s teaching chart.

Clarinet

Choose Clarinet for a Boehm soprano instrument in B♭ or A. The setup combobox also saves your choice for other sessions. This first version supports written E3–C6; altissimo and other key systems are outside its fingering table.

Select a written note directly on the score. Gold marks the target; register exercises also outline the starting note. Register · twelfths practises the lower-to-clarion relationship, with the register key shown separately from the thumb hole. Alternate fingerings includes verified left/right little-finger choices. Press Listen to hear the sounding pitch of the written target.

The contact diagram uses circles for holes and ovals for levers. Gold means cover or press. The microphone checks pitch and timing; it cannot confirm the finger contacts. The basic fingerings follow the Woodwind Fingering Guide’s chalumeau and clarion tables.

In Play, clarinet parts use a horizontal diagram, with a smaller preview of the next different fingering above it. The score and playhead carry the timing; there is no falling-note highway. A short cue shows when to start and how much of the note remains. The trainer retains its upright contact map.

Bending Trainer

Play → Note Trainer → Harmonica 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.

Reading the selected target

The focus card names the hole and says whether to breathe in (draw) or out (blow), including the direction needed for bends and overblows/overdraws. The staff shows the target in gold. When the exercise changes the reed’s pitch, its natural starting note appears in white before the target. These notes follow the chosen harp key. The bend rail remains the live feedback surface, and the technique map remains the target selector.

On a shorter window, the focus card scrolls so the notation and practice controls remain reachable while the technique selector stays beside it.

Lessons

Play → Lessons first asks which instrument you play: harmonica, guitar, piano or flute. The game then loads only that instrument’s lessons and text. Use Back from the tree to choose another instrument. If no course is installed for your choice, the page says so and points to Options → Lessons & songs.

The selected curriculum is 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.

Flute: first steps

The flute path begins with setup and a steady B4, then introduces breathing, rests and pulse. Next, connect B4–A4–G4, add C5 and D5, and play short phrases using those five notes. An E4/E5 octave exercise is optional after the main path. A fourth unit teaches note lengths, counted rests, paired eighth notes and phrasing in 3/4, using the notes already learned. All exercises fit both C-foot and B-foot concert flutes.

Thirteen short exercises use the normal flute score and horizontal fingering view. Pitch and timing count toward passing; posture, comfortable breathing, fingering choice and articulation quality need your own listening or a teacher’s feedback. The setup lesson is completed by self-assessment.

Piano: first steps

Nine lessons take you from locating middle C to a short two-hand piece. Begin with right-hand C4–G4, then read left-hand C3–G3 on the bass staff. Alternating-hand exercises and counted rests prepare the first simultaneous entrances. The last core exercise combines a melody with simple bass notes; a C-major chord lesson is optional afterward.

The eight playable exercises fit any keyboard covering C3–G4 and use the normal grand staff and full keyboard view. For simultaneous notes, select FFT or NMF chord detection in Options. The microphone checks sounding pitches and timing; hand choice, fingering, posture and balance need your own attention or a teacher’s feedback.

Guitar: first steps

Ten lessons introduce a six-string guitar in standard E–A–D–G–B–E tuning without a capo. Learn all six open strings, then frets 1 and 3 on strings 1 and 2. A two-string melody and counted rests lead to an E-minor arpeggio. An Em strum is optional after the main path.

The nine playable exercises carry explicit string and fret positions and show sounding pitches. The arpeggio sounds one string at a time; the optional strum needs FFT or NMF chord detection. Scoring cannot identify the string, finger or strum direction, so check the written positions and listen for unwanted string noise as well as following the score.

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.

Harmonica: 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.

Choosing an instrument

Opening a fresh editor asks you to choose Harmonica, Guitar, Piano, Bass, or Flute. Returning to an existing draft keeps its instrument and notes. New opens the chooser again; replacing a document with content asks for confirmation. Save first to retain that draft. Cancelling keeps it intact. In an empty document, Details → Instrument can also change the instrument. Loading a chart uses its saved instrument configuration; like New, it asks before replacing a document that has content. The Details pane provides Save, New, and Load beside the instrument choices, so you can save a populated chart and start a document for another instrument.

The grid, score, timeline, metadata, selection and undo tools are shared. Each instrument supplies its own note positions, techniques, validation and serialization. Harmonica tuning, playing position, recording, MIDI-to-harp mapping and lesson authoring are shown only for harmonica documents.

Guitar charts

Choose Guitar for a new document to start a standard-tuned guitar chart. Load also opens existing guitar .harpchart files and preserves their tuning and capo. A guitar chart uses the same grid, tools and timeline as a harmonica chart, with one lane per string instead of one per hole — highest string at the top, as tab writes it, each labelled with its open note in its string’s colour. A note is drawn in its string’s colour (the same as on the play highway) and reads as tab: 7 for a fret, 7b9 for a bend up to the pitch of fret 9, <12> for a harmonic.

Tuning and strings

Details has a Guitar tuning combobox for named six-string tunings. It shows Custom when individual pitches do not match a preset. Guitar setup below it provides an editable pitch for each string. Use scientific pitch names with an octave (E4, F#3, Bb2); string 1 is the top tab row. Add string and Remove last string change the count from 1 to 12, including 7- and 10-string setups. Added bass strings start a fourth below the previous string, stopping at C0; edit their pitches to match your instrument. Named presets replace the whole string list with six strings.

Retuning keeps fret positions and changes sounding pitches. Setup changes can be undone and are retained when saving and loading. Removing an occupied string is refused: move or delete its notes first. All existing notes must remain playable. Up to 12 strings are independent tab lanes; paired courses on a conventional 12-string guitar are not automatically linked.

The note column swaps the harmonica’s breath and reed buttons for the guitar’s:

  • Fret − / Fret + move the selected note a fret down or up on its string. With nothing selected they set the fret a click places the next note at; the button shows that fret.
  • String ↑ / String ↓ move the selected note to the string above or below at whichever fret keeps its pitch, and refuse when that string can’t reach it. A successful move eases into its new row; a refused move nudges toward that row and returns, with a status message. Dragging a note to another lane instead keeps its fret.
  • Bend steps through a half-step bend, a whole-step bend and off; Harmonic toggles a natural harmonic where the fret has one. Vibrato colours only its own string’s note.

Everything else — selecting, dragging, resizing, copy/paste, undo, Play, the staff and the timeline tools — works as it does for a harmonica. Harmonica transposition, Wah and Record are hidden: recording needs real-guitar detection, which still needs validating against recordings.

No edit puts two overlapping notes on one string, or asks for a hand span the guitar can’t make, held notes included; one that would is refused and the status bar says so. Return to a harmonica from Details with the document empty.

Flute charts

Choose Flute for a new document to start a flute chart; Load opens existing ones with their foot joint. The grid has a keyboard beside one row per pitch, C7 at the top down to the flute’s lowest note (C4, or B3 with a B foot), rows drawn narrower so the whole range fits. Click a row to place a note there; a flute plays one note at a time, so a new note ends the one sounding and a note can’t start with another. Each note shows its name, and D6·1 means its first alternate fingering.

The note column has Fingering, which steps the selected note through its fingerings (the button shows which, e.g. 2/3), plus vibrato and its depth, the phrase buttons, transpose (♯ ♭, a semitone, onto each new note’s standard fingering) and delete.

Fingering view (♫ in the left column) turns the rows into the flute’s keys, from the thumb key at the top to the foot rollers, and draws each note as the fingering that plays it: a block on every key it presses. Press it again for note view. A key isn’t a pitch, so in fingering view notes move only in time: select, drag sideways, resize, delete, copy and paste, and the note column all work, while new notes are placed in note view.

Piano charts

Choose Piano for a new document. Each row is a key; simultaneous notes can form chords or two-hand passages. The editor shows a scrollable 24-key window, centered on the notes when a chart loads. Notes outside the visible window remain in the document. The Play screen’s full keyboard is independent of this editing window. Preview uses the piano voice. The score uses a grand staff with treble and bass clefs, showing the upper and lower registers together.

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 New/Save/Load. The right column is about the note — the selected one, or the next one you’ll place: instrument-specific positions and techniques (for harmonica, Blow/Draw, bend/overblow/overdraw or slide), 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, with string, pitch or hole rows for the chosen instrument, 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 staff uses the song’s key signature and spells accidentals accordingly. Guitar and bass notes appear an octave above their sounding pitches, with an octave-below clef indication; previews still play the sounding pitch.
  • 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. A bend is played on the reed that bends, so it sets the breath too: a bend on holes 1–6 is a draw and on 8–10 a blow, and blowing a bent note on hole 3 drops the bend. 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 instrument 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 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.

Scale and Time Signature are in the fixed area at the top of Details, alongside the instrument’s tuning controls. Their dropdowns remain outside the scrolling form so the option lists stay accessible.

Chart metadata

The shared Details form covers tempo, musical key, background music and song name/author. Instrument-specific controls appear alongside it: harmonica documents additionally offer playing position and harmonica type (standard, Paddy Richter, country-tuned or natural-minor diatonic; 12-/16-hole chromatic).

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 instrument voice used for that chart 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

For harmonica documents, 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

For harmonica documents, 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, available for harmonica documents, 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:

KeyAction
Ctrl+Z / Ctrl+YUndo / redo
Ctrl+C / Ctrl+VCopy the current selection / paste it at the mouse position
Delete / BackspaceDelete the current selection
Ctrl+↑ / Ctrl+↓Transpose the selection, or the whole chart, by one semitone
Ctrl+Shift+↑ / Ctrl+Shift+↓Transpose by one octave
← / → (Arrow Left/Right)Pan the grid horizontally
EscClear the current selection or a pending timeline split, then back out of the editor

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.

Bass documents

Choose Bass when starting a new document. Its tab grid and editing tools reuse the fretted-string editor: click a string to add a note, choose its fret, and use the string controls to move it while preserving pitch. The score uses octave-transposing bass clef; the chart stores sounding pitches.

Details → Bass setup accepts custom pitches for individual strings. The tuning combobox offers standard four-, five- and six-string setups and Drop D. Retuning keeps authored fret positions and updates their sounding pitches; setup edits are rejected atomically if existing notes would become unplayable. Saved documents retain the distinct bass identity and appear under Bass in the song list’s instrument filter.

Bass charts use song format 1.11.0. Bass lesson manifests require lesson format 3; existing curricula using format 2 remain supported. Selecting Bass in Lessons loads only its namespace and shows an empty state when no bass curriculum is installed.

Cavaquinho documents

Choose Cavaquinho for a four-string document in the named Brazilian traditional tuning. Details → Cavaquinho setup offers named presets and individual string pitches, including octaves. The editor preserves the distinct cavaquinho identity on save and load. Notes and positions use the shared fretted editor; unsupported guitar technique controls remain hidden. Custom tunings stay with the document and can be played as written.

Cavaquinho charts use song format 1.12.0; cavaquinho lesson manifests require lesson format 4. Selecting Cavaquinho in Lessons reads only its namespace and shows an empty state when no curriculum is installed.

Clarinet documents

Choose Clarinet when creating a document, then choose a B♭ or A Boehm soprano setup under Details. The piano-shaped input and grid use concert pitch; the notation staff shows written clarinet pitches and their transposed key signature. A reminder above the grid distinguishes these two conventions.

Changing setup preserves sounding pitches and assigns the new instrument’s standard fingerings. If a note would leave the supported written E3–C6 range, the editor keeps the existing setup and explains the failure. Fingering cycles the selected note’s available alternatives. Charts save sounding notes and stable fingering indices, using song format 1.13.0.

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 Play 2D.
  • 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.

My instruments

What you play on, so you only say it once:

  • Guitar tuning — the tuning your guitar is in, or As each song is written to follow each chart. A song written for another tuning plays the same notes on the frets yours needs.
  • Guitar capo — the fret your capo is on, No capo, or as each song is written.
  • Flute foot joint — a C or B foot, or as each song is written. Notes below your foot are shown but not counted.
  • Flute fingering chart — shown or hidden under a flute part’s highway; the same setting as the pause menu’s Fingering chart.

The page before each guitar or flute song opens on these, and an answer given there is saved here too.

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

KeyAction
EscPause/resume during a song; go back one menu level otherwise.
MouseAll menu navigation and pause-menu buttons.

During gameplay (Play 2D / Jam Session)

KeyAction
MMute/unmute the metronome click (visual beat indicator keeps working).
VCycle the spectrogram’s visual style.

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

Song Editor

KeyAction
Ctrl+Z / Ctrl+YUndo / redo
Ctrl+C / Ctrl+VCopy the selection / paste it at the mouse position
Delete / BackspaceDelete the selection
← / →Pan the grid
EscClear the selection, or back out of the editor

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

KeyAction
Tab / Shift+TabMove keyboard focus to the next / previous control.
Enter or SpaceActivate whatever has focus.
Arrow keysMove between the options of a focused tab bar or radio group; nudge a focused slider (← / →).
Home / EndSend a focused slider to its minimum / maximum.
EscClose an open dropdown, cancel a file dialog, or back out one menu level — whichever applies where you are.

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%
  • Sections — click one above the paused score to select it
  • Repeat section — loop the selected section; toggle again to stop
  • Phrase coverage toggle, and a slider for how much of the selected section is revealed

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