Working with Chords

A chord is two or more tones sounding simultaneously. Chords are the vertical dimension of music — while melody moves horizontally through time, harmony stacks tones on top of each other.

Chord Construction

Chords are built by stacking intervals above a root note. The most common chord type is the triad — three notes built from alternating scale degrees (root, 3rd, 5th).

The four triad types:

Major       root + major 3rd (4) + perfect 5th (7)    Bright, stable
Minor       root + minor 3rd (3) + perfect 5th (7)    Dark, sad
Diminished  root + minor 3rd (3) + diminished 5th (6) Tense, unstable
Augmented   root + major 3rd (4) + augmented 5th (8)  Eerie, unresolved

Adding a 7th creates a seventh chord — the foundation of jazz harmony:

Dominant 7th   root + 4 + 7 + 10   Bluesy, wants to resolve (G7)
Major 7th      root + 4 + 7 + 11   Dreamy, sophisticated (Cmaj7)
Minor 7th      root + 3 + 7 + 10   Warm, mellow (Am7)
Diminished 7th root + 3 + 6 + 9    Dramatic, symmetrical

Inversions

A chord is in root position when the root is the lowest note. When a different chord tone is in the bass, the chord is inverted:

  • Root position: C E G (root in bass)

  • First inversion: E G C (3rd in bass) — notated C/E

  • Second inversion: G C E (5th in bass) — notated C/G

Inversions change the color and weight of a chord without changing its identity. First inversion sounds lighter; second inversion sounds suspended, often used as a passing chord.

For seventh chords, there’s also third inversion (7th in bass):

  • G7 in third inversion: F G B D (notated G7/F)

from pytheory import Chord, Tone

# All three are "C major" — identify() finds the root
root     = Chord([Tone.from_string(n, system="western") for n in ["C4", "E4", "G4"]])
first    = Chord([Tone.from_string(n, system="western") for n in ["E3", "G3", "C4"]])
second   = Chord([Tone.from_string(n, system="western") for n in ["G3", "C4", "E4"]])

root.identify()     # 'C major'
first.identify()    # 'C major'
second.identify()   # 'C major'

Extended Chords

Beyond seventh chords, jazz harmony builds extended chords by continuing to stack thirds:

  • 9th chord: adds the 9th (= 2nd, one octave up)

  • 11th chord: adds the 9th and 11th (= 4th)

  • 13th chord: adds the 9th, 11th, and 13th (= 6th)

A full 13th chord contains all 7 notes of the scale! In practice, tones are usually omitted — the 5th is typically dropped first, then the 11th (which clashes with the 3rd in dominant chords).

from pytheory import TonedScale

scale = TonedScale(tonic="C4")["major"]

# Build a Cmaj9 from the scale: C E G B D
cmaj9 = scale.chord(0, 2, 4, 6, 8)

# Build a full C13 (in theory): C E G B D F A
c13 = scale.chord(0, 2, 4, 6, 8, 10, 12)

Using the Chord Chart

PyTheory includes 144 pre-built chords (12 roots x 12 qualities):

from pytheory import CHARTS

chart = CHARTS["western"]

c_major = chart["C"]     # C major (root position)
a_minor = chart["Am"]    # A minor
g_seven = chart["G7"]    # G dominant 7th
d_dim   = chart["Ddim"]  # D diminished

Available qualities:

Quality

Intervals

Example tones (from C)

""

4, 7

C E G (major triad)

"maj"

4, 7

C E G (explicit major)

"m"

3, 7

C Eb G (minor triad)

"5"

7

C G (power chord)

"7"

4, 7, 10

C E G Bb (dominant 7th)

"9"

4, 7, 10, 14

C E G Bb D (dominant 9th)

"dim"

3, 6

C Eb Gb (diminished)

"m6"

3, 7, 9

C Eb G A (minor 6th)

"m7"

3, 7, 10

C Eb G Bb (minor 7th)

"m9"

3, 7, 10, 14

C Eb G Bb D (minor 9th)

"maj7"

4, 7, 11

C E G B (major 7th)

"maj9"

4, 7, 11, 14

C E G B D (major 9th)

 
>>> chart["C"].acceptable_tone_names
('C', 'E', 'G')

>>> chart["Cm7"].acceptable_tone_names
('C', 'D#', 'G', 'A#')    # Eb and Bb shown as sharps

Building Chords Manually

from pytheory import Tone, Chord

c_major = Chord(tones=[
    Tone.from_string("C4", system="western"),
    Tone.from_string("E4", system="western"),
    Tone.from_string("G4", system="western"),
])

for tone in c_major:
    print(tone)

len(c_major)       # 3
"C" in c_major     # True

Intervals

The intervals property returns semitone distances between adjacent tones — these are musically meaningful and octave-invariant:

>>> c_major.intervals
[4, 3]    # major 3rd (4) + minor 3rd (3) = major triad

>>> Chord(tones=[C4, Eb4, G4]).intervals
[3, 4]    # minor 3rd + major 3rd = minor triad

Consonance and Dissonance

Consonance is the perception of stability and “pleasantness” when tones sound together. Dissonance is the perception of tension and roughness. Neither is inherently good or bad — music needs both.

Harmony Score

The harmony property measures consonance using frequency ratio simplicity. The insight dates back to Pythagoras (6th century BC): intervals whose frequencies form simple integer ratios sound consonant.

Interval

Ratio

Why it sounds “good”

Octave

2:1

Every 2nd wave aligns

Perfect 5th

3:2

Every 3rd wave aligns

Perfect 4th

4:3

Every 4th wave aligns

Major 3rd

5:4

Every 5th wave aligns

Minor 3rd

6:5

Every 6th wave aligns

Tritone

45:32

Waves rarely align

 
fifth = Chord([C4, G4])
tritone = Chord([C4, F_sharp_4])

fifth.harmony > tritone.harmony     # True
# The perfect fifth's 3:2 ratio scores higher

Dissonance Score

The dissonance property uses the Plomp-Levelt roughness model (1965). When two frequencies are close together, their sound waves interfere and produce rapid amplitude fluctuations called beating. This beating is perceived as roughness — the physiological basis of dissonance.

The roughness depends on the frequency difference relative to the critical bandwidth of the human ear (~25% of the frequency at that register). Maximum roughness occurs when the difference equals the critical bandwidth.

# Octave: frequencies far apart → low roughness
octave = Chord([C4, C5])
# Major 3rd: closer frequencies → higher roughness
third = Chord([C4, E4])

octave.dissonance < third.dissonance  # True

Beat Frequencies

When two tones with slightly different frequencies are played together, you hear a pulsing at the beat frequency: |f1 - f2| Hz.

  • < 1 Hz: Slow pulsing, used for tuning instruments

  • 1–15 Hz: Audible rhythmic beating

  • 15–30 Hz: Perceived as buzzing/roughness

  • > 30 Hz: No longer beating — becomes part of the timbre

chord = Chord(tones=[A4, E5, A5])

# All pairwise beat frequencies, sorted ascending
chord.beat_frequencies
# [(A4, E5, 189.6), (E5, A5, 220.0), (A4, A5, 440.0)]

# The slowest (most perceptible) beat
chord.beat_pulse  # 189.6 Hz

Chord Identification

Give PyTheory any set of tones and it will tell you what chord it is. It tries every tone as a potential root and matches the interval pattern against 17 known chord types (triads, 7ths, 9ths, sus, power chords).

from pytheory import Chord, Tone

# Build a chord and identify it
chord = Chord([
    Tone.from_string("A4", system="western"),
    Tone.from_string("C5", system="western"),
    Tone.from_string("E5", system="western"),
])
chord.identify()   # 'A minor'

# Works with any voicing or inversion
chord2 = Chord([
    Tone.from_string("E4", system="western"),
    Tone.from_string("G4", system="western"),
    Tone.from_string("C5", system="western"),
])
chord2.identify()  # 'C major' (first inversion detected)

Harmonic Analysis

Roman numeral analysis labels each chord by its function within a key. This is how musicians describe chord progressions independent of key — “I-IV-V” means the same thing in C major (C-F-G) as in G major (G-C-D).

from pytheory import Chord, Tone

C4 = Tone.from_string("C4", system="western")
D4 = Tone.from_string("D4", system="western")
E4 = Tone.from_string("E4", system="western")
F4 = Tone.from_string("F4", system="western")
G4 = Tone.from_string("G4", system="western")
A4 = Tone.from_string("A4", system="western")
B4 = Tone.from_string("B4", system="western")

Chord([C4, E4, G4]).analyze("C")              # 'I'    (tonic)
Chord([D4, F4, A4]).analyze("C")              # 'ii'   (supertonic minor)
Chord([G4, B4, G4+5]).analyze("C")            # 'V'    (dominant)
Chord([G4, B4, G4+5, G4+10]).analyze("C")     # 'V7'   (dominant 7th)

Tension and Resolution

Tension is what makes music move forward. Without it, there’s no desire to resolve — no drama, no narrative. The tension property quantifies this based on:

  • Tritones (6 semitones): the most unstable interval. The tritone between the 3rd and 7th of a dominant chord (e.g. B and F in G7) creates the strongest pull toward resolution.

  • Minor 2nds: semitone clashes that add bite and urgency.

  • Dominant function: the specific combination of a major 3rd and minor 7th above the root — the hallmark of the V7 chord.

# A C major triad is fully resolved — no tension
c_major = Chord([C4, E4, G4])
c_major.tension['score']               # 0.0
c_major.tension['tritones']            # 0

# G7 is loaded with tension — it wants to resolve to C
g7 = Chord([G4, B4, G4+5, G4+10])
g7.tension['score']                    # 0.6
g7.tension['tritones']                 # 1
g7.tension['has_dominant_function']     # True

Voice Leading

Voice leading is the art of connecting chords smoothly. Instead of jumping all voices to new positions, good voice leading moves each note the minimum distance to reach the next chord. Bach’s chorales are the gold standard — every voice moves by step whenever possible.

c_maj = Chord([C4, E4, G4])
f_maj = Chord([F4, A4, C4+12])

for src, dst, motion in c_maj.voice_leading(f_maj):
    print(f"{src} -> {dst}  ({motion:+d} semitones)")
# Each voice moves the minimum distance to reach the target chord

The Overtone Series

Every musical tone is actually a stack of frequencies — the fundamental plus its overtones (harmonics). The overtone series is nature’s chord: it contains the octave, perfect fifth, perfect fourth, major third, and more, in that order.

This is why consonance exists. When you play C and G together, the overtones of C already contain G. The two tones share acoustic energy, reinforcing each other. A dissonant interval like C and C# shares almost no overtones — the waves clash.

from pytheory import Tone

a4 = Tone.from_string("A4", system="western")
a4.overtones(8)
# [440.0, 880.0, 1320.0, 1760.0, 2200.0, 2640.0, 3080.0, 3520.0]
#  A4     A5     E6      A6      C#7     E7      ~G7     A7
#  fund.  oct.   5th+oct 2oct    3rd     5th     ~7th    3oct