What the Hell Chord Did I Just Play?

I built a little MIDI display for jazz practice: choose a key and mode, then see chord names, Roman numerals, and harmonic functions.

I wanted to learn jazz harmony and connect the chord symbols on a page to what I was playing. So I built a little keyboard display that names chords as I play them and shows their function in a key and mode I choose.

Play C, E, G and B, and it shows Cmaj7. Put the E at the bottom, and it shows Cmaj7/E. Add a ninth, leave out the fifth, spread the notes between both hands: those are the sorts of voicings I wanted it to understand.

The project, Chord Display, runs on an M5Stack Core2 touchscreen. My keyboard sends it MIDI wirelessly through a WIDI Master. The piano makes the sound; the box watches the notes, including those held by the sustain pedal.

Dadd9, Gm7, C7 and back, with the key set to C Ionian. Unmute for the piano.
Chord Display naming chords on a stage piano

A hand plays chords on a stage piano while the Core2 display sits above the keys, set to C Ionian. Each time a chord sounds, its name appears in large type with a Roman numeral underneath: Dadd9, Gm7, C7, then Dadd9 again. Gm7 shows v7, flagged as possibly borrowed from minor. Between chords the screen clears.

A name for the thing under your fingers

Jazz chord symbols pack a lot into a small space. Cmaj7, C7 and Cm7 change by a note or two, but they suggest different sounds and different places to go next. Once the ninths, altered tones and slash basses arrive, there’s more to connect to your hands and ears.

I wanted to play a voicing, hear it, read the symbol, then change a note and compare. The screen uses familiar names such as Cmaj7 and Cm7b5, with alterations stacked in smaller parentheses.

The main view puts the chord name in large type, with notes and degrees underneath. The harmony view places it against my chosen key or mode. The staff view shows the notes on a grand staff in their actual registers. Held and pedal-sustained notes use different colors.

The same chord can have a different job

Choosing a key and mode gives the analyzer a musical context. Alongside the chord name, it shows a Roman numeral and a reading of the chord’s function: tonic, predominant, dominant, or something outside the selected scale.

In C major, G7 is V7, the dominant pulling toward C. Select G Mixolydian, and that same G7 becomes I7, the modal home chord. The notes and chord name stay the same; their relationship to the home I’ve chosen changes.

That gives me a way to practice beyond naming isolated shapes. In C major, Dm7, G7 and Cmaj7 trace ii–V–I on the screen: predominant, dominant, tonic. The display keeps a short trail of recent chords so I can follow that movement. In D Dorian, adding B to Dm7 brings in the mode’s natural sixth, which the display highlights as a color tone.

The reference stays where I put it; a chromatic note doesn’t make the device decide I’ve changed keys. I choose the context and listen. A label can’t settle whether a voicing belongs in a tune, or what the bass player will make of it.

How it decides what to call a chord

The analyzer starts with the notes arriving over MIDI. For naming a chord, several Cs in different octaves count as the same note. It still keeps the lowest note and the original registers for slash basses and staff notation.

It then tries each possible root and compares the intervals above it with known chord shapes: major and minor triads, sevenths, suspended chords, and extended or altered chords. A match has to explain every note that’s sounding. Some tones can be omitted, such as the perfect fifth in many jazz voicings, while the notes that establish the chord’s quality have to be present.

It also recognizes literal stacks of fourths and fifths, often called quartal and quintal voicings. Those can have ordinary chord names too, so the spacing label describes the voicing without pretending it establishes a unique root or harmonic function.

For rootless voicings, E, B and D can suggest Cmaj9: the third, major seventh and ninth, with the C left out. The box can show that reading with a question mark for the inferred root. A compatible reading with its root present gets priority.

Some collections have several good names. C, E, G and A can be C6 or Am7. The bass helps choose the main reading, and an ALSO line shows useful alternatives. There’s only so much a handful of simultaneous notes can tell you about the music around them.

C6 and Am7: the bass guides the name
Only A moves, down one octave. The note names stay the same; the bass and preferred label change. R marks the named root. Both readings remain possible.

Two piano voicings contain C, E, G and A. Lowering A3 to A2 leaves C3, E3 and G3 in place and changes the analyzer's main label from C6 to Am7. The keyboards show each note's degree above the named root and retain the other rooted reading.

View source values
Constructed examples run through the analyzer. Moving A3 to A2 preserves pitch classes, not the exact sounding pitches. Other readings remain possible; question marks qualify inferred roots. R marks the named root.
BassPlayed low to highMain labelOther rooted readingInferred readingDegrees above the named root
C3C3 – E3 – G3 – A3C6Am7/CFmaj9/C?C3: R · E3: 3 · G3: 5 · A3: 6
A2A2 – C3 – E3 – G3Am7C6/AFmaj9/A?A2: R · C3: b3 · E3: 5 · G3: b7
Constructed examples run through the analyzer. Moving A3 to A2 preserves pitch classes, not the exact sounding pitches. Other readings remain possible; question marks qualify inferred roots. R marks the named root.
BassPlayed low to highMain labelOther rooted readingInferred readingDegrees above the named root
C3C3 – E3 – G3 – A3C6Am7/CFmaj9/C?C3: R · E3: 3 · G3: 5 · A3: 6
A2A2 – C3 – E3 – G3Am7C6/AFmaj9/A?A2: R · C3: b3 · E3: 5 · G3: b7

The recognition code began with Long Kelvin’s MIDI Chord Detector. I adapted it for this device and worked on its handling of jazz voicings, omitted notes and alternative readings. It runs locally on the box.

Build one, or break this one

The source, setup instructions and tests are on GitHub. The project is open source under the MIT license, with the upstream detector and music-font credits included.

The printed case. A magnet in the base holds it on top of the keyboard.
Printing the case

A timelapse from inside a 3D printer as the Chord Display's open-topped case builds up layer by layer on the print bed.

If it gets a voicing wrong, an issue with the notes you played, the bass note and the name you expected would help. Ambiguous names are useful examples too, especially when the surrounding progression explains the reading you had in mind.

Now I can sit at the keyboard, play a chord, and see both its name and how it fits the key and mode I’m practicing.