enharmonic

Real-time enharmonic pitch spelling for MIDI.

A written score names each note with a letter and an accidental. A MIDI stream keeps only the twelve pitch classes and throws that away: it cannot say whether note 61 is a C♯ or a D♭. The letter is not cosmetic. It tells a reader the note's harmonic identity. This library recovers it from musical context alone.

The idea

A spelling can be wrong in two independent ways. The first is coherence: inside an F‑minor chord, note 68 is A♭, not G♯, because G♯ would make an augmented second where the ear hears a minor third. The second is the comma, or side: a passage in C♯ major written in D♭ major is the same pitches one turn around the spiral of fifths, a coherent transposition, not an error.

The speller works in one harmonic space, with no key detection anywhere. Three principles handle coherence: an interval score that rewards consonance, a running seven-letter scale, and a recency guard against flicker. A spiral of fifths then decides which side of the comma a passage sits on. The side it lands on is a statistic of the notes it has already committed.

Those three principles, plus a spiral fold that pulls the scale back one comma when it drifts too far, are small enough to read in one file: the Core speller, about 100 lines with zero imports. The fold only catches a large drift, so Core can still land a passage on the wrong side of the comma. The shipped modes track the side more closely.

One speller

One engine spells each note as it plays, from past context only. An optional look-ahead setting reads a small forward buffer to fix the direction a semitone resolves. An offline two-pass option reads the whole piece forward and backward, then reconciles the two to repair the modulation boundaries the streaming pass spells late.

Modeexactcoherent
Core (4 principles)99.37%99.46%
Real-time99.62%99.69%
Look-ahead99.85%99.90%
Two-pass99.94%99.94%

Meredith (216 movements, 195,972 notes) is the standard pitch-spelling benchmark; these are its clean scores. Exact is a composer-spelling match; coherent also counts flipped notes (below). Each mode beats the published speller of its latency there: real-time beats Chew & Chen, look-ahead beats Cambouropoulos, two-pass beats PKSpell.

Held-out collections

The same spellers, untouched, on collections none of their rules were built on. PKSpell, a neural speller, has the highest exact rate of the published spellers on these sets; like two-pass it reads the whole piece.

Collection Two-pass (ours) PKSpell
exact coherent exact coherent
OpenScore Lieder (397 songs)97.23%99.22%97.03%98.49%
DCML corpora (498 pieces)97.56%99.14%97.34%98.67%
ASAP piano, unseen by PKSpell (18)89.00%97.34%93.09%96.14%
Four new collections (5,356 pieces)98.43%99.42%98.10%99.07%

Two-pass makes fewer wrong notes than PKSpell on every set, the unseen ASAP pieces included; PKSpell matches the composer's side more often there. Per-set tables, every speller and the significance tests are on the scoreboard.

The gap between exact and coherent is flipped notes. A flip is a coherent transposition: a whole passage spelled consistently on the other side of the spiral (C♯ major for D♭ major), the same music, not a wrong note. Almost every miss is a flip, not an error.

Pieces played back to back

Most spellers assume one piece in one key. Feed them the 48 preludes and fugues of Bach's Well-Tempered Clavier, Book I, as one continuous stream, the way a live player or a long MIDI file would, and they carry the last piece's key into the next. Our spellers (in blue) follow each key change:

Spellerwrong notes, one streamwrong notes, restarted per piece
Two-pass0.17%0.13%
Look-ahead0.20%0.18%
Real-time0.42%0.43%
Longuet-Higgins0.62%0.56%
Cambouropoulos2.99%2.82%
ps134.04%0.28%
Chew & Chen4.83%0.89%
music2114.53%14.53%

Restarted at every piece, ps13 is close to our spellers; in one stream it makes 14 times as many errors, because it fixes its reference from the first notes. Chew & Chen averages the key over everything heard. Ours keep a local collection, so a new key simply replaces the old one. (Exact rates are lower for everyone here, since 24 keys leave many coherent side choices. PKSpell, trained on these pieces, is left out.)