Jazz Music Theory

Pitch Class Assignment

C=0  C#/Db=1  D=2  D#/Eb=3  E=4  F=5  F#/Gb=6  G=7  G#/Ab=8  A=9  A#/Bb=10  B=11

Enharmonic equivalents map to the same integer: F# and Gb are both 6.

MIDI Note to Pitch Class

pitch_class = midi_note % 12
# MIDI 60 (middle C) → 60 % 12 = 0 → C
# MIDI 64 (E4)       → 64 % 12 = 4 → E

Interval = Difference Mod 12

interval = (note_pc - root_pc) % 12
# From C (0) to E (4): (4 - 0) % 12 = 4 → major 3rd
# From A (9) to C (0): (0 - 9) % 12 = 3 → minor 3rd

Generating Scale Notes Across the Piano

To find all MIDI notes belonging to a scale, iterate MIDI 21-108 and check membership:

def get_scale_midi_notes(root_pc: int, intervals: tuple[int, ...],
                         low: int = 21, high: int = 108) -> list[int]:
    return [m for m in range(low, high + 1) if (m - root_pc) % 12 in intervals]

2. Scale Definitions

Each scale is a tuple of semitone intervals from the root. These are the scales used in the project:

Symmetric scales (diminished, whole-tone) have 6 or 8 notes instead of 7. The half-whole and whole-half diminished scales are inversions of each other: half-whole starts with a half step (used over dominant chords), whole-half starts with a whole step (used over diminished chords).

Modes of Harmonic Minor

Modes of Melodic Minor

Several important jazz scales are modes of the melodic minor scale:

3. Chord-Scale Theory

Default Quality-to-Scale Mapping

This is Layer 1 of the harmony analyzer — the fallback when no context rule applies:

Extension Overrides

When a chord has parenthesized extensions, they override the default scale:

4. Chord Tones, Guide Tones, and Tensions

Chord Tones

The essential notes that define the chord (root, 3rd, 5th, 7th), expressed as semitone intervals from the root:

Guide Tones

The 3rd and 7th of each chord. These two notes:

• Define the chord quality (major vs minor vs dominant)
• Move by small intervals (half step or whole step) across chord changes
• Are the primary target notes in the Guide Tone exercise

def get_guide_tones(root_pc: int, quality: str) -> tuple[int, int]:
    """Return (3rd_pc, 7th_pc) for the chord."""
    third = (root_pc + CHORD_TONES[quality][1]) % 12  # 3 or 4 semitones
    seventh = (root_pc + CHORD_TONES[quality][3]) % 12  # 9, 10, or 11 semitones
    return (third, seventh)

For triads without a 7th (maj, min, aug), the guide tone is just the 3rd.

Available Tensions

Scale tones that are NOT chord tones. These add color without clashing:

Avoid notes: Scale tones a half step above a chord tone create dissonance when sustained. In Ionian, the 4th (F over Cmaj7) is an avoid note because it's a half step above the 3rd (E). The projection doesn't distinguish avoid notes — all scale tones are shown — but this matters for the walking bass and exercise target note selection.

5. Context-Aware Resolution (Layer 2)

These rules override the default scale when the harmonic context is clear. Each rule examines (prev_chord, current_chord, next_chord).

Rule 1: V7 Resolving to Minor

Pattern: X:7 → Y:<minor> where X is a 5th above Y (i.e. (X_root - Y_root) % 12 == 7), and <minor> is any quality starting with min (i.e. min7, min, minmaj7, min6, min9, min11, min13, etc.).

Scale: Phrygian dominant (5th mode of harmonic minor)

Why: The b9 and b13 of Phrygian dominant are the characteristic tones of a V7 in minor. Mixolydian (the default) has a natural 9 and 13, which sound like a major-key dominant.

G:7 → C:min7   →  G Phrygian dominant (G Ab B C D Eb F)
                   = C harmonic minor starting on G

Detection: (current_chord.root_pc - next_chord.root_pc) % 12 == 7 AND next_chord.quality.startswith("min").

Rule 2: Tritone Substitution

Pattern: X:7 → Y where X is a half step above Y (root moves down by 1 semitone).

Scale: Lydian dominant

Why: A tritone sub replaces a V7 with a dominant chord a tritone away. Lydian dominant has a #11, which is the enharmonic equivalent of the original dominant's root — it connects the two keys smoothly.

Db:7 → C:maj7  →  Db Lydian dominant (Db Eb F G Ab Bb Cb)
                   The G (= #11 of Db) is the 5th of C, linking the resolution

Detection: (current_chord.root_pc - next_chord.root_pc) % 12 == 1 AND current_chord.quality == "7" (exact match — excludes 7sus4 slash-chord spellings from tritone sub detection).

Rule 3: Extended ii-V Chain (iii-vi-ii-V)

Pattern: A chain of chords whose roots each ascend by P4 (5 semitones), ending with a ii-V pair. Common forms:

vi-ii-V:     A:min7 → D:min7 → G:7        (roots: 9→2→7, each +5 mod 12)
iii-vi-ii-V: E:min7 → A:min7 → D:min7 → G:7
iii-VI7-ii-V: E:min7 → A:7 → D:min7 → G:7  (A:7 is a secondary dominant V/ii)

Scale: All chords in the chain share the key center of the final resolution target. Each chord gets the diatonic mode for its degree — this overrides the Layer 1 default of Dorian for iii and vi:

Secondary dominants (7 chords within the chain that resolve to a minor chord) get Phrygian dominant via Rule 1.

Why: This is a descending-fifths cycle — the most common harmonic motion in jazz. Recognizing the full chain (not just isolated ii-V pairs) helps identify secondary dominants and confirms the key center for all chords.

Detection: Identify a ii-V pair (a min* chord followed by a 7* chord with roots a P4 apart), then walk backwards. Each preceding chord is part of the chain if (current_chord.root_pc - prev_chord.root_pc) % 12 == 5 AND prev_chord.quality.startswith("min") or prev_chord.quality.startswith("7").

Rule 4: I-vi-ii-V Turnaround

Pattern: W:maj7 → X:min7 → Y:min7 → Z:7 where the I chord's root is a minor 3rd above the vi chord's root, followed by a descending-fifths chain (Rule 3).

C:maj7 → A:min7 → D:min7 → G:7   (I-vi-ii-V in C major)

Scale: Same key-center logic as Rule 3. The I chord confirms the key unambiguously:

Why: The I-vi-ii-V turnaround is one of the most common progressions in jazz standards. The I chord anchors the key center, making it the strongest confirmation that vi should get Aeolian (not the default Dorian).

Detection: A Rule 3 chain is preceded by a chord where prev_chord.quality.startswith("maj") AND (prev_chord.root_pc - current_chord.root_pc) % 12 == 3. The I → vi root motion is a minor 3rd down (3 semitones), unlike the P4 motion within the chain.

Rule 5: IV Chord in Major Context

Pattern: X:maj7 where the previous chord or key context suggests X is the IV degree.

Scale: Lydian (instead of default Ionian)

Why: The #4 of Lydian avoids the clash between the natural 4 and the major 3rd of the chord. When a maj7 chord is clearly functioning as a IV chord, Lydian is the idiomatic jazz choice.

Detection: (current_chord.root_pc - prev_chord.root_pc) % 12 == 5 AND both prev_chord.quality.startswith("maj") AND current_chord.quality.startswith("maj").

Rule 6: Half-Diminished Standalone

Pattern: X:hdim7 where the next chord is NOT dominant-function (its default scale ∉ {mixolydian, lydian_dominant, phrygian_dom, altered}).

Scale: Locrian ♮9 (locrian_nat9)

Why: When hdim7 is not resolving to a dominant (not acting as ii° in a minor ii°–V), the natural 9 is idiomatic. Contrast:

• hdim7 → dominant → Locrian ♮6 (natural 13, ii° of minor ii°-V-i)
• hdim7 standalone → Locrian ♮9 (natural 9, 6th mode of melodic minor)

Detection: current_chord.quality.startswith("hdim") AND next_chord is None or its default scale is not in DOMINANT_SCALES.

Resolution Priority

When multiple rules could apply, use this priority:

1. Extension overrides (explicit b9, #9, etc.) — always win
2. Context rules (V→minor, tritone sub, ii-V)
3. Default quality lookup

6. Voice-Leading Principles

Guide-Tone Voice-Leading

The harmony analyzer pre-computes a guide-tone line across the entire form. At each chord transition, pick the guide tone (3rd or 7th) that is closest in pitch to the previous guide tone.

Dm7    → G7     → Cmaj7
3rd=F    3rd=B     3rd=E
7th=C    7th=F     7th=B

Guide-tone line: F → F → E  (7th of G7 = F, same as 3rd of Dm7; then 3rd of Cmaj7 = E, half step down)

Key voice-leading connections in jazz:

• 3rd of ii → 7th of V (same note or half step): e.g., Dm7 3rd (F) = G7 7th (F)
• 7th of V → 3rd of I (half step down): e.g., G7 7th (F) → Cmaj7 3rd (E)
• 7th of ii → 3rd of V (half step down): e.g., Dm7 7th (C) → G7 3rd (B)

This is what makes ii-V-I progressions sound smooth — the guide tones descend by half step.

Implementation

def compute_guide_tone_line(chords: list[ChordEvent]) -> list[int]:
    """Return one MIDI note per chord: the voice-led guide tone."""
    line = []
    prev_note = None
    for chord in chords:
        third_pc, seventh_pc = get_guide_tones(chord.root_pc, chord.quality)
        # Find closest octave placement of each candidate to prev_note
        candidates = find_nearest_midi(third_pc, prev_note) + find_nearest_midi(seventh_pc, prev_note)
        if prev_note is None:
            chosen = pick_from_middle_register(candidates)  # start in a comfortable range
        else:
            chosen = min(candidates, key=lambda n: abs(n - prev_note))
        line.append(chosen)
        prev_note = chosen
    return line

7. Walking Bass Construction

Principles

A walking bass line plays one note per beat (quarter notes) and outlines the harmony while creating melodic motion.

Strong beats (1 and 3): Chord tones — root, 3rd, 5th, 7th. Beat 1 strongly prefers the root.

Weak beats (2 and 4): Scale tones, chromatic approach notes, or passing tones connecting the strong beats.

Beat 4 → Beat 1 (next chord): The most important connection. Beat 4 should approach the root of the next chord by:

• Half step above or below (chromatic approach) — strongest
• Whole step (diatonic approach)
• The 5th of the next chord (dominant approach)

Range

Bass range: MIDI 28 (E1) to MIDI 48 (C3). This matches the range of an upright bass. Notes should generally move by step or small skip (2nds or 3rds), with occasional larger leaps (4ths, 5ths) for variety.

Step-by-Step Algorithm

For each bar with chord X:

1. Beat 1: Root of X (in bass range). If repeating the same chord as previous bar, may use 5th or 3rd for variety.
2. Beat 2: Scale tone between beat 1 and beat 3 (stepwise motion).
3. Beat 3: 5th of X, or another chord tone (3rd, 7th). Should differ from beat 1.
4. Beat 4: Approach note targeting beat 1 of the next bar's chord — chromatic half step above/below the next root.

Direction and Contour

• Alternate ascending and descending motion across bars to stay within range.
• If approaching the range ceiling (MIDI 48), walk downward. If approaching the floor (MIDI 28), walk upward.
• Avoid staying on the same note for consecutive beats (walking = motion).

Two-Beat Chords

When a chord lasts only 2 beats:

• Beat 1: Root
• Beat 2: Approach note to the next chord's root

8. Swing Timing

What Swing Is

In swing feel, each beat is divided into two unequal parts instead of two equal eighth notes. The first eighth is longer, the second is shorter — like a triplet with the first two notes tied:

Straight: |-----|-----|  (50/50 split)
Swing:    |-------|---|  (67/33 split, triplet feel)

Swing Ratio

The swing_ratio parameter controls the split:

• 0.50 = straight (no swing) — each eighth note is exactly 50% of a beat
• 0.67 = triplet swing (default) — the downbeat eighth is 67% of a beat, the upbeat is 33%
• 0.75 = hard swing — exaggerated shuffle feel

Application

Swing is applied during event generation, not during playback. The timeline stays in straight time (chord changes happen on beat boundaries). Only the backing track events (bass notes, drum hits on the "and" of beats) get their timing shifted:

def apply_swing(beat_position: float, swing_ratio: float = 0.67) -> float:
    """Shift offbeat eighth notes forward in time."""
    beat_fraction = beat_position % 1.0
    if abs(beat_fraction - 0.5) < 0.01:  # this is an offbeat ("and")
        beat_int = int(beat_position)
        return beat_int + swing_ratio  # shift the "and" later
    return beat_position

What Gets Swung

• Ride cymbal "skip" notes (the "and" of 2 and 4)
• Walking bass — if any notes fall on offbeats (rare in standard walking, but possible in rhythmic variations)
• Ghost snare notes if placed on offbeats

What Does NOT Get Swung

• Quarter-note hits (beats 1, 2, 3, 4) — these stay on the grid
• Hi-hat pedal on 2 and 4 — these are on the beat
• Chord changes — always on beat boundaries
• The timeline clock — stays in straight time for chord lookup

9. Chord Symbol Parsing

Grammar

SYMBOL = ROOT ":" QUALITY [EXTENSION] [BASS]
ROOT = C | C# | Db | D | D# | Eb | E | F | F# | Gb | G | G# | Ab | A | A# | Bb | B
QUALITY = <string> — matched by prefix family (see Parsing Strategy below)
EXTENSION = "(" ALTERATION {"," ALTERATION} ")"
ALTERATION = b5 | b6 | #5 | b9 | #9 | #11 | b13 | 13
BASS = "/" ROOT

Parsing Strategy

1. Split on : to separate root from the rest
2. Extract parenthesized extensions with regex: \(([^)]+)\)
3. Extract slash bass note: /[A-G][#b]?$
4. What remains is the quality string — classify by prefix family rather than exact match:

No prefix collisions exist in the current set, but check in the order listed for clarity. Within a family, use the full quality string to look up the exact default scale from Layer 1; fall back to the family's base quality if no exact match.

Enharmonic Normalization

The parser must handle both sharp and flat spellings. Both F#:min7 and Gb:min7 refer to the same pitch class (6). Normalize to a canonical spelling when computing pitch classes, but preserve the original spelling for display.

Slash-Chord Spellings of 7sus4

Two patterns are recognized and reclassified as 7sus4 rooted on the bass note:

The quality not startswith("7") guard on the first pattern prevents mis-detecting E:7/F# as a dominant sus4. After reclassification, all chord tones and scale notes use the bass note as root, Mixolydian scale.

10. Common Jazz Progressions (Reference)

These patterns appear frequently in the lead sheet corpus and inform context-aware resolution:

Related Skills

• python-design-patterns — Architecture and separation of concerns for the harmony module
• python-testing-patterns — TDD approach for harmony and walking bass correctness