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.
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.
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
| Bass | Played low to high | Main label | Other rooted reading | Inferred reading | Degrees above the named root |
|---|---|---|---|---|---|
| C3 | C3 – E3 – G3 – A3 | C6 | Am7/C | Fmaj9/C? | C3: R · E3: 3 · G3: 5 · A3: 6 |
| A2 | A2 – C3 – E3 – G3 | Am7 | C6/A | Fmaj9/A? | A2: R · C3: b3 · E3: 5 · G3: b7 |
| Bass | Played low to high | Main label | Other rooted reading | Inferred reading | Degrees above the named root |
|---|---|---|---|---|---|
| C3 | C3 – E3 – G3 – A3 | C6 | Am7/C | Fmaj9/C? | C3: R · E3: 3 · G3: 5 · A3: 6 |
| A2 | A2 – C3 – E3 – G3 | Am7 | C6/A | Fmaj9/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.
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.