Apps, music theory, optimisation
A tension-aware chord-progression analyser, reharmoniser and guitar-voicing optimiser, built with my band's songwriting in mind. All of it runs in the browser, with no server and no model API.
Code on GitHub: hyh4867/progression-lab ↗
Chords separated by spaces; | marks bars (chords in a bar share its four beats); % repeats. Slash chords like C/E work. Or pick a named progression further down.
Detected key
C major
Confidence 86% (relative score, not a probability) · best correlation r = 0.94 · runner-up A minor (0.85)
Ambiguous: A minor (relative key) fits almost as well. Choose a key above if you hear it differently.
1 of 3 root moves are rising fifths.
Hover, tap or step through the chords to follow the path.
Shaded wedge: the C key window (IV–I–V); the ringed slot is the tonic.
Outer ring: major chords · middle: minor (under the relative major) · inner: diminished
Tap a chord for its explanation (* = function inferred from the root degree). Tap a device below the chords to highlight its span. The lock keeps a chord fixed when reharmonising.
Solid: tension of your progression (simplified Lerdahl Tonal Pitch Space distance from the tonic, plus movement and added-tone dissonance). Dashed: the target. Draw on the chart or drag a point; focused points respond to the arrow keys.
Set a target curve, then press Reharmonise. The search tries named substitution rules and returns the five best alternatives, each no farther from the target than your original.
One voicing per chord, chosen by dynamic programming (Viterbi) to minimise hand movement, voice-leading distance and fingering difficulty. Standard tuning; frets 0–15; 4-fret stretch.
C G Am F e|0--3--0---x--| B|1--0--1---1--| G|0--0--2---2--| D|2--0--2---3--| A|3--2--0---0--| E|x--3--x---1--|
I – V – vi – IV
C G Am F
All four chords are diatonic and share tones pairwise, so the loop moves smoothly; V→vi is a built-in deceptive move that keeps it circling.
I – vi – IV – V
C Am F G
Tonic, its relative minor, a predominant and the dominant: one full functional cycle (T–T–PD–D) that ends on V and pulls straight back to I.
I – V – vi – iii – IV – I – IV – V
D A Bm F#m G D G A
A descending bass (D–C#–B–A–G–F#–G–A) under chords a fourth apart; each chord shares a tone with the next, so it can repeat for ever.
ii7 – V7 – Imaj7
Dm7 G7 Cmaj7
Predominant → dominant → tonic with roots falling by fifths; the 7ths resolve down by step into the next chord's 3rd.
I7 – IV7 – I7 – I7 – IV7 – IV7 – I7 – I7 – V7 – IV7 – I7 – V7
A7 | D7 | A7 | A7 | D7 | D7 | A7 | A7 | E7 | D7 | A7 | E7
Three dominant-seventh chords in a fixed 12-bar frame; the b7s are blues colour rather than tensions that must resolve, and bar 12's V7 turns the form around.
i – VII – VI – V
Am | G | F | E
Four chords step down the minor scale to a major V, whose raised leading tone makes the loop sound like a half cadence (Phrygian colour).
I – bVII – IV – I
D C G D
bVII replaces V, so the loop never uses the leading tone; IV and bVII are both a whole step from their neighbours, giving a relaxed rock sound.
I – bVI – bVII – I
C Ab Bb C
Two major chords borrowed from the parallel minor rise by whole steps into the tonic: a triumphant cadence with no V chord.
Can a small, explainable music-theory model help a band find better chord changes, and show why they work?
A zero-dependency TypeScript engine reads chord symbols (sevenths, extensions, alterations, sus chords and slash basses) and finds the key. It does this by correlating a duration-weighted pitch-class histogram with Krumhansl–Kessler key profiles.
Every chord gets a Roman numeral and exactly one function: tonic, predominant, dominant or passing. When no device explains a chord, its function is inferred from its root degree and marked as inferred. The analyser names secondary dominants, augmented sixths, the Neapolitan, common-tone and passing diminished chords, chromatic mediants, altered dominants and modal interchange (naming the source mode). Augmented triads and diminished sevenths are read by where they resolve. Each chord comes with a one- or two-sentence explanation.
Across several chords it marks pedal points, line clichés, lament basses, Mixolydian and Dorian vamps and Coltrane cycles. A sliding-window key tracker smoothed by dynamic programming separates modulations from brief tonicisations and finds pivot chords.
A circle-of-fifths view draws the progression as a path on three rings (major, minor, diminished), shades the key's diatonic window, and marks each root move by colour and line style, so falling-fifth chains, tritone substitutions and Coltrane triangles are visible at a glance.
A simplified version of Lerdahl's Tonal Pitch Space turns the progression into a tension curve. You draw a target curve, and a beam search returns up to five alternatives, each with a plain-language reason for every change. It uses seven named substitution rules plus four optional advanced ones: augmented-sixth approach, Neapolitan approach, backdoor ii–V and chromatic-mediant substitution.
A library of 35 named progressions, from the axis progression to Coltrane changes, loads into the analyser in any key. Each progression lists one or two well-known songs by title and artist only, and a song was listed only if a web source confirmed that it uses the progression.
A voicing generator enumerates playable shapes in standard tuning, and a Viterbi dynamic program picks one per chord, trading hand movement against voice-leading and fingering difficulty. A Karplus–Strong plucked-string synth strums the result, and a capo helper and a text tab make it usable at rehearsal.
Key finding is scored on 52 progressions whose keys I labelled by hand before running the algorithm. Nine are deliberately hard cases (modal vamps, relative-key loops, blues dominants, power chords) and stay in the headline figure. The profile weights were fixed in advance, not tuned on this set.
Advanced harmony is scored on a second hand-labelled set of 44 progressions. Their expected devices, functions, spans and key regions were written down and committed before the analyser was built. A progression counts as a match only if every expectation holds.
Property tests transpose every labelled progression into all 12 keys and require identical key positions, Roman numerals, functions, devices, cadences and tension values. The voicing optimiser is checked against exhaustive search, and the reharmoniser is run on 260 target-curve and lock combinations.
Song examples for the library were checked one by one against web sources (Wikipedia articles first, then lessons and analyses), and every kept example stores its source.
The detected key matched my label on 47 of 52 progressions (90.4%); the correct key was in the top two for all 52 (MIREX-weighted score 0.919). Three of the five misses were flagged as ambiguous by the tool itself.
On the advanced set, 44 of 44 progressions matched every expectation (103 of 103 individual checks). This is not a blind score: while implementing, I made one general fix (key tracking starts in the home key) that also fixed one entry.
55 of 56 candidate song examples were confirmed by a web source; 1 was dropped because no source showed the device. The library shows only the one or two best-known songs per progression (38 in total).
The dynamic-programming voicing path equalled the brute-force optimum on 52 of 52 small cases.
Across 260 reharmonisation runs, locked chords never changed, every suggested chord parsed back to the same notes, and no suggestion was farther from the target curve than the original. 206 automated tests pass in the site repository; the public repository runs 201 of them, leaving out the five that check this page's text.
I chose the music-theory models, the labelled sets and their expected answers, the substitution rules, and what counts as a fair test.
Claude helped implement the engine, tests, library research and interface in bounded milestones. I reviewed its output and kept responsibility for the claims on this page; every number above is produced by the test suite.
Western tonal and jazz harmony only. The model does not read melody, lyrics or audio, so it cannot judge whether a chord fits the tune you sing over it.
Labels are rule-based. Where a chord has several valid readings (an augmented sixth versus a tritone substitute, bVI as mixture or as a chromatic mediant), the tool picks one by fixed rules and lists the others. Functions marked as inferred are guesses from the root degree.
The tension model is a simplified Tonal Pitch Space: no prolongational tree, heuristic weights for added-tone dissonance, and chromatic chords treated as inflections of the home key. Its curve is a guide, not a measurement of how listeners hear tension.
Suggestions come from fixed substitution rules ranked by a score. They are not taste, they do not know your genre, and a lower score is not a promise that a change sounds better.
Both labelled sets were chosen and labelled by me, so their scores say little about real repertoire. Key confidence is a relative score, not a calibrated probability, and voicing difficulty is a hand-set heuristic.
Song examples are verified from web sources but not exhaustive. A listed song may use the progression in only one section, or in another key.
Engine, tests and documentation are in the public repository (src/, docs/progression_lab.md, docs/tension_model.md). The labelled sets are in src/corpus.ts and src/advancedCorpus.ts, the library and its sources in src/library.ts. Chord sequences only; songs are referenced by title and artist, with no melodies or lyrics.
Krumhansl, Cognitive Foundations of Musical Pitch (1990) ↗
Lerdahl, Tonal Pitch Space (2001) ↗
Karplus & Strong, Digital synthesis of plucked-string and drum timbres (1983) ↗