JamBuddy/docs/progression-repertoire.md

Chord Progression Repertoire

Research-backed reference for expanding the progression features. Companion to GOAL.md Part 1. Notation: uppercase = major, lowercase = minor, ° = diminished, 7 = dominant unless marked maj7/m7.

How this maps to code today:

• PROGRESSIONS in src/lib/theory.js — { name, rn, degrees } per progression; degrees are semitone offsets from the key root. This is the format new entries should use.
• getSuggestedProgressions(root, mode) maps degrees → chord names in key; toRomanNumeral() converts any chord back to a numeral.
• FAMOUS_PROGRESSIONS in src/lib/education.js — richer entries (songs, tips, style variations) for the Learn side.

1. Genre-by-genre progression tables

Pop

Progression	Name / notes
I–V–vi–IV	"Axis of Awesome" — #1 in Hooktheory's corpus of 75k+ analyzed songs
vi–IV–I–V	Same loop rotated to start on vi ("pessimistic axis")
I–vi–IV–V	"Doo-wop" / "'50s progression"
I–IV–vi–V	Common variant (Africa chorus)
IV–V–iii–vi	"Royal Road" — J-pop/anime staple, spreading into Western pop

Rock

Progression	Name / notes
I–IV–V	Foundation of rock/blues/country
I–♭VII–IV(–I)	Mixolydian rock cliché (Sweet Home Alabama as V–IV–I rotation)
i–♭VII–♭VI(–V)	Andalusian-derived minor loop; with V = full Andalusian cadence
I–♭III–IV	Blues-rock riff progression (borrowed ♭III)

Blues (12-bar family)

Progression	Name / notes
I7×4 / IV7×2, I7×2 / V7, IV7, I7, V7	Standard 12-bar
Bar 2 → IV7	"Quick change" / "quick four"
ii7–V7 in bars 9–10, turnaround I–VI7–ii–V7	Jazz blues
i7–iv7–i7 … ♭VI7–V7–i7	Minor blues (The Thrill Is Gone)
I–V–IV–IV–I–V–I–V	8-bar blues (Key to the Highway)

Jazz

Progression	Name / notes
ii7–V7–Imaj7	The fundamental cadence
I–vi–ii–V (also iii–vi–ii–V)	Rhythm changes A / turnaround
III7–VI7–II7–V7	Rhythm changes bridge (circle of dominants)
iim7♭5–V7♭9–i	Minor ii–V–i
ii7–♭II7–Imaj7	Tritone-sub cadence
ivm7–♭VII7–Imaj7	"Backdoor" progression

Folk / Country

Progression	Name / notes
I–IV–V(–I)	Core of both genres
I–V–I–IV	Two/three-chord verse pattern
i–♭VII–♭VI	Minor folk descent (Am–G–F)
I–V–vi–iii–IV–I–IV–V	Pachelbel progression
I–II7–V–I	Classic country secondary-dominant (V/V) move

Funk

Progression	Name / notes
I7 vamp	James Brown static dominant, voiced as 9th
i7–IV7	Dorian two-chord vamp — the most common funk pair
i7 / m11 vamp	Minor one-chord groove
ii7–V7 loop	Funk/disco vamp

Design insight: funk needs few progressions but rich chord qualities (9, 7♯9, m11, 13sus) — colour lives in the voicing, not the changes.

Reggae

Progression	Name / notes
I–V or I–IV	Two-chord skank vamps
I–V–vi–IV	No Woman No Cry
i–♭VII(–♭VI)	Minor roots-reggae vamp
I–IV–V	Ska/rocksteady standard

R&B / Neo-soul

Progression	Name / notes
ii7–V7–Imaj7 (with 9/11/13 extensions)	Core cadence
iii7–vi7–ii7–V7	Circle movement from the mediant — neo-soul staple
vi–ii–V–I	"6-2-5-1" cyclical soul loop
Imaj7–IVmaj7 / Imaj7–iii7	Two-chord vamps
i7–iv7	Dorian D'Angelo-style minor vamp

Gospel

Progression	Name / notes
ii7–V7–I	The gospel "2-5-1", often chained: 6-2-5-1, 3-6-2-5-1
I–I7–IV	Tonicizing IV (V7/IV "amen" setup)
IV–iv–I	Plagal with borrowed iv
I–♯i°–ii	Chromatic passing-diminished walk-up

2. Substitution / variation taxonomy

Progression "families" relate through a small set of transforms — these are the generation rules for variation buttons and the Builder:

1. Rotation — any loop can start on any chord (I–V–vi–IV ≡ vi–IV–I–V). Treat loops as cyclic equivalence classes; display the rotation matching the user's tonic emphasis. (detectRepeatingProgression already canonicalizes rotations.)
2. Diatonic (function) substitution — chords sharing two notes swap: I↔vi↔iii (tonic), IV↔ii (subdominant), V↔vii° (dominant).
3. Modal interchange / borrowing — take a chord from the parallel mode: iv, ♭VI, ♭VII, ♭III, iim7♭5 in major; major IV (Dorian) in minor.
4. Secondary dominants — precede any diatonic target with its V7: V/V = II7, V/vi = III7, V/IV = I7, V/ii = VI7.
5. Tritone substitution — replace any dominant with the dominant a tritone away (V7 → ♭II7). Jazz flavour flag.
6. Backdoor dominant — ♭VII7 resolving to I, usually as ivm7–♭VII7–I.
7. Quality embellishment — same root, richer colour: triad → 7th → 9/11/13, sus2/4, add9. The main axis distinguishing genres (pop = triads/sus, jazz/neo-soul/gospel = extensions, funk = dominant 9/♯9). Already partially covered by CHORD_SUBSTITUTIONS in education.js.
8. Passing/approach chords — chromatic passing diminished (I–♯i°–ii), bass-line inversions (slash chords).

3. UX patterns worth copying

• Hookpad (Hooktheory) — key-relative chord palette: only the diatonic chords of the current key, colour-coded consistently per scale degree (key-agnostic colours). Borrowed chords live in expandable secondary palettes. Magic Chord suggests the statistically likeliest next chord. Drag-and-drop onto a timeline. → Direct model for the Progression Builder (GOAL G3).
• Hooktheory TheoryTab — progressions ranked by real-song frequency; each links to songs using it. "You're playing the Creep progression" is a strong engagement hook (partially exists via FAMOUS_PROGRESSIONS song lists).
• Scaler 2/3 — three-zone vertical flow: detection area (top) → suggested chords/scales (middle) → user-built progression (bottom). Maps directly onto this app: live detection → suggestions → builder.
• iReal Pro — one-tap transposition; per-genre rendering of the same progression.
• ToneGym — instant audio preview when tapping any chord/progression.

4. Voicing data

Guitar

Best option found: tombatossals/chords-db (MIT, npm @tombatossals/chords-db, prebuilt lib/guitar.json):

• All 12 keys × large suffix list, multiple positions per chord (open + barre + higher CAGED positions).
• Per position: frets (per string, x = mute, low-E first), fingers, optional barres, baseFret. Example: { frets: '55775x', fingers: '114310', barres: 5 }.
• Companion renderer: tombatossals/react-chords (React SVG diagrams consuming this format).

Triads on string-sets (top-3 / middle-3) are not in chords-db but are cheap to generate: for each inversion of the triad, map the 3 chord tones onto a chosen string set within a 4-fret window. This complements the existing GUITAR_SHAPES in src/lib/voicings.js.

Piano

No canonical open dataset exists. The sane model is interval recipes resolved per chord quality (the chord templates in theory.js already encode quality → semitone mapping):

// voicing = named recipe of chord degrees, resolved per chord quality
{
  shell:        { LH: ['1', '7'],           RH: ['3'] },
  rootPosition: { LH: ['1'],                RH: ['1', '3', '5', '7'] },
  rootlessA:    { LH: ['3', '5', '7', '9'] },  // Type A: 3rd on bottom
  rootlessB:    { LH: ['7', '9', '3', '5'] },  // Type B: 7th on bottom
  guideTones:   { LH: ['3', '7'] },
}

Conventions to encode: rootless voicings keep the top note between C4–C5; alternate Type A/B through a progression so inner voices barely move — i.e. pick the voicing minimizing semitone travel from the previous chord (simple voice-leading distance minimization).

5. Sources

• Hooktheory corpus & blog: hooktheory.com/blog/i-analyzed-the-chords-of-1300-popular-songs-for-patterns-this-is-what-i-found/ ; hooktheory.com/blog/jazz-chord-progressions/
• 12-bar variants: en.wikipedia.org/wiki/Twelve-bar_blues ; happybluesman.com/common-variations-12-bar-blues/
• Named progressions: en.wikipedia.org/wiki/%2750s_progression ; piano.org/chord-progressions/ ; supersimplepiano.com/learn/chord-progressions/royal-road
• Substitutions: learnjazzstandards.com (chord substitution) ; hub.yamaha.com (beyond diatonic) ; hubguitar.com (tritone subs)
• Gospel: gospelmaps.com/top-gospel-chord-progressions/ ; gospel.hearandplay.com (2-5-1)
• Genre vamps: orphiq.com (reggae) ; guitar-chord.org/articles/funk.html ; orangecandymusic.com & pickupmusic.com (R&B/neo-soul)
• Tools: producelikeapro.com (Scaler review) ; hooktheory.com/hookpad
• Voicing data: github.com/tombatossals/chords-db ; github.com/tombatossals/react-chords ; voicinglab.com & pianowithjonny.com & thejazzpianosite.com (rootless voicings)