mirror of
https://github.com/kennethreitz/pytheory.git
synced 2026-06-05 23:00:20 +00:00
Add Music Theory Fundamentals page and deepen theory throughout docs
New: Music Theory Fundamentals guide covering: - Sound and pitch (frequency ranges, logarithmic perception) - Why twelve notes (harmonic series, Pythagorean comma) - Intervals as atoms of music (size, quality, perfect vs major/minor) - Keys and key signatures (sharp/flat key tables, FCGDAEB mnemonic) - Functional harmony (tonic/subdominant/dominant, T-S-D-T) - The dominant seventh (leading tone, tritone resolution) - Rhythm and meter (4/4, 3/4, 6/8, odd meters) - Physics of consonance (waveform alignment, cultural context) Enriched existing pages: - Tones: overtone series table, enharmonic equivalents and spelling rules - Scales: 12-bar blues, parallel major/minor, borrowed chords, more progression examples with song references - Chords: inversions (root/1st/2nd/3rd), extended chords (9ths/11ths/13ths) Also: add Gauges analytics tracking to all pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Vendored
+18
@@ -0,0 +1,18 @@
|
||||
{% extends "!layout.html" %}
|
||||
{% block footer %}
|
||||
{{ super() }}
|
||||
<script type="text/javascript">
|
||||
var _gauges = _gauges || [];
|
||||
(function() {
|
||||
var t = document.createElement('script');
|
||||
t.type = 'text/javascript';
|
||||
t.async = true;
|
||||
t.id = 'gauges-tracker';
|
||||
t.setAttribute('data-site-id', '69bfc431e7e47c1200fc74bc');
|
||||
t.setAttribute('data-track-path', 'https://track.gaug.es/track.gif');
|
||||
t.src = 'https://d2fuc4clr7gvcn.cloudfront.net/track.js';
|
||||
var s = document.getElementsByTagName('script')[0];
|
||||
s.parentNode.insertBefore(t, s);
|
||||
})();
|
||||
</script>
|
||||
{% endblock %}
|
||||
@@ -27,6 +27,63 @@ harmony::
|
||||
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)
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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).
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
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
|
||||
---------------------
|
||||
|
||||
|
||||
+55
-1
@@ -208,6 +208,60 @@ Some of the most-used chord progressions in Western music:
|
||||
|
||||
- **I–IV–V–I** — the foundation of blues, rock, country, folk
|
||||
- **I–V–vi–IV** — the "pop progression" (Let It Be, No Woman No Cry,
|
||||
With or Without You)
|
||||
With or Without You, Someone Like You)
|
||||
- **ii–V–I** — the backbone of jazz harmony
|
||||
- **I–vi–IV–V** — the "50s progression" (Stand By Me, Every Breath You Take)
|
||||
- **i–bVI–bIII–bVII** — the "epic" minor progression (Stairway to Heaven,
|
||||
My Heart Will Go On)
|
||||
- **I–IV–vi–V** — axis of awesome (many, many pop songs)
|
||||
|
||||
The 12-Bar Blues
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The **12-bar blues** is the most influential chord progression in
|
||||
American music. It's 12 measures long and uses only three chords
|
||||
(I, IV, V)::
|
||||
|
||||
| I | I | I | I |
|
||||
| IV | IV | I | I |
|
||||
| V | IV | I | V |
|
||||
|
||||
Every blues, early rock and roll, and much of jazz is built on this
|
||||
structure. In the key of A::
|
||||
|
||||
| A | A | A | A |
|
||||
| D | D | A | A |
|
||||
| E | D | A | E |
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import TonedScale
|
||||
|
||||
a = TonedScale(tonic="A4")["major"]
|
||||
I = a.triad(0) # A major
|
||||
IV = a.triad(3) # D major
|
||||
V = a.triad(4) # E major
|
||||
|
||||
# The 12-bar blues progression
|
||||
blues_12 = [I, I, I, I, IV, IV, I, I, V, IV, I, V]
|
||||
|
||||
Parallel Major and Minor
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Two scales are **relative** if they share the same notes (C major and
|
||||
A minor). Two scales are **parallel** if they share the same tonic but
|
||||
have different notes (C major and C minor).
|
||||
|
||||
Mixing parallel major and minor is a powerful compositional tool —
|
||||
borrowing chords from the parallel minor in a major key creates
|
||||
dramatic color shifts. The bVI and bVII chords (Ab and Bb in C major)
|
||||
are borrowed from C minor and appear constantly in rock and film music.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
c_major = TonedScale(tonic="C4")["major"]
|
||||
c_minor = TonedScale(tonic="C4")["minor"]
|
||||
|
||||
# Compare: same tonic, different notes
|
||||
c_major.note_names # ['C', 'D', 'E', 'F', 'G', 'A', 'B', 'C']
|
||||
c_minor.note_names # ['C', 'D', 'D#', 'F', 'G', 'G#', 'A#', 'C']
|
||||
|
||||
@@ -0,0 +1,254 @@
|
||||
Music Theory Fundamentals
|
||||
=========================
|
||||
|
||||
This page covers the essential concepts of music theory — the framework
|
||||
behind everything PyTheory does.
|
||||
|
||||
Sound and Pitch
|
||||
---------------
|
||||
|
||||
All sound is vibration. When an object vibrates, it pushes air molecules
|
||||
back and forth, creating pressure waves that travel to your ears. The
|
||||
speed of this vibration — measured in cycles per second (Hertz, Hz) —
|
||||
determines the **pitch** you hear.
|
||||
|
||||
- **20 Hz**: the lowest pitch most humans can hear
|
||||
- **60–250 Hz**: the range of the human voice (speaking)
|
||||
- **261.63 Hz**: middle C (C4)
|
||||
- **440 Hz**: the tuning standard A (A4)
|
||||
- **4186 Hz**: the highest C on a piano (C8)
|
||||
- **20,000 Hz**: the upper limit of human hearing
|
||||
|
||||
The relationship between pitch and frequency is **logarithmic** — each
|
||||
octave doubles the frequency. This means the distance from A3 (220 Hz)
|
||||
to A4 (440 Hz) is 220 Hz, but the distance from A4 to A5 (880 Hz) is
|
||||
440 Hz. Both sound like "one octave" to our ears.
|
||||
|
||||
Why Twelve Notes?
|
||||
-----------------
|
||||
|
||||
The Western chromatic scale has 12 notes per octave. This isn't arbitrary —
|
||||
it emerges from the physics of vibrating strings and air columns.
|
||||
|
||||
The **harmonic series** is the sequence of frequencies produced when a
|
||||
string vibrates: f, 2f, 3f, 4f, 5f... The relationships between these
|
||||
harmonics create the intervals we perceive as consonant:
|
||||
|
||||
- 2:1 = octave (the most fundamental)
|
||||
- 3:2 = perfect fifth
|
||||
- 4:3 = perfect fourth
|
||||
- 5:4 = major third
|
||||
- 6:5 = minor third
|
||||
|
||||
If you stack perfect fifths (multiply by 3/2 repeatedly) and reduce to
|
||||
within one octave, you get 12 roughly evenly-spaced notes before the
|
||||
cycle almost closes. The tiny gap where it doesn't close perfectly is
|
||||
the **Pythagorean comma** — the reason we need temperament.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import Tone
|
||||
|
||||
# Walk the circle of fifths — all 12 notes
|
||||
c = Tone.from_string("C4", system="western")
|
||||
[t.name for t in c.circle_of_fifths()]
|
||||
# ['C', 'G', 'D', 'A', 'E', 'B', 'F#', 'C#', 'G#', 'D#', 'A#', 'F']
|
||||
|
||||
Other cultures divide the octave differently: Indonesian gamelan uses
|
||||
5 or 7 unequal divisions; Indian classical music theoretically has 22
|
||||
shrutis (microtones); Arabic maqam uses quarter-tones.
|
||||
|
||||
Intervals: The Atoms of Music
|
||||
------------------------------
|
||||
|
||||
An **interval** is the distance between two pitches. Intervals are the
|
||||
building blocks of everything — melodies are sequences of intervals,
|
||||
chords are stacks of intervals, and scales are patterns of intervals.
|
||||
|
||||
Every interval has two properties:
|
||||
|
||||
**Size** (how many scale steps)::
|
||||
|
||||
Unison → 2nd → 3rd → 4th → 5th → 6th → 7th → Octave
|
||||
|
||||
**Quality** (exact number of semitones)::
|
||||
|
||||
Perfect: unison (0), 4th (5), 5th (7), octave (12)
|
||||
Major: 2nd (2), 3rd (4), 6th (9), 7th (11)
|
||||
Minor: 2nd (1), 3rd (3), 6th (8), 7th (10)
|
||||
Augmented: one semitone larger than perfect or major
|
||||
Diminished: one semitone smaller than perfect or minor
|
||||
|
||||
The "perfect" intervals (unison, 4th, 5th, octave) are called perfect
|
||||
because they appear in both major AND minor scales unchanged. They've
|
||||
been considered consonant across virtually all musical cultures
|
||||
throughout history.
|
||||
|
||||
The **tritone** (augmented 4th / diminished 5th = 6 semitones) divides
|
||||
the octave exactly in half. Medieval theorists called it *diabolus in
|
||||
musica* ("the devil in music") because of its extreme instability.
|
||||
Today it's the foundation of dominant harmony and the blues.
|
||||
|
||||
Keys and Key Signatures
|
||||
-----------------------
|
||||
|
||||
A **key** is a group of notes that form the tonal center of a piece.
|
||||
The key of C major uses only the white keys on the piano: C D E F G A B.
|
||||
The key of G major uses the same notes except F becomes F#.
|
||||
|
||||
Key signatures tell you which notes are sharped or flatted throughout
|
||||
a piece. They follow the circle of fifths:
|
||||
|
||||
**Sharp keys** (add one sharp per step clockwise)::
|
||||
|
||||
C major: no sharps or flats
|
||||
G major: F#
|
||||
D major: F# C#
|
||||
A major: F# C# G#
|
||||
E major: F# C# G# D#
|
||||
B major: F# C# G# D# A#
|
||||
|
||||
**Flat keys** (add one flat per step counter-clockwise)::
|
||||
|
||||
C major: no sharps or flats
|
||||
F major: Bb
|
||||
Bb major: Bb Eb
|
||||
Eb major: Bb Eb Ab
|
||||
Ab major: Bb Eb Ab Db
|
||||
Db major: Bb Eb Ab Db Gb
|
||||
|
||||
The order of sharps is always F C G D A E B (Father Charles Goes Down
|
||||
And Ends Battle). The order of flats is the reverse: B E A D G C F.
|
||||
|
||||
Harmony: How Chords Work
|
||||
-------------------------
|
||||
|
||||
**Harmony** is the art of combining tones simultaneously. While melody
|
||||
is horizontal (tones in sequence), harmony is vertical (tones stacked).
|
||||
|
||||
The simplest harmony is the **triad** — three notes built by stacking
|
||||
thirds. The quality of each third determines the chord type:
|
||||
|
||||
- **Major triad** = major 3rd + minor 3rd (e.g. C-E-G)
|
||||
- **Minor triad** = minor 3rd + major 3rd (e.g. C-Eb-G)
|
||||
- **Diminished triad** = minor 3rd + minor 3rd (e.g. B-D-F)
|
||||
- **Augmented triad** = major 3rd + major 3rd (e.g. C-E-G#)
|
||||
|
||||
In any major key, the triads built on each scale degree always follow
|
||||
the same pattern::
|
||||
|
||||
Degree Quality Function
|
||||
I Major Tonic (home)
|
||||
ii Minor Pre-dominant
|
||||
iii Minor Tonic substitute
|
||||
IV Major Subdominant (departure)
|
||||
V Major Dominant (tension, wants to go home)
|
||||
vi Minor Tonic substitute, relative minor
|
||||
vii° Diminished Dominant substitute (leading tone chord)
|
||||
|
||||
This pattern is the DNA of Western harmony. Pop songs, classical
|
||||
sonatas, jazz standards, and church hymns all derive from it.
|
||||
|
||||
Functional Harmony
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Chords don't just have names — they have **functions**:
|
||||
|
||||
- **Tonic function** (I, iii, vi): stability, rest, home
|
||||
- **Subdominant function** (ii, IV): motion away from home
|
||||
- **Dominant function** (V, vii°): tension, desire to return home
|
||||
|
||||
The most fundamental progression in Western music is **T → S → D → T**
|
||||
(tonic → subdominant → dominant → tonic). The classic I-IV-V-I is
|
||||
exactly this pattern. Every "Louie Louie" and every Bach chorale follows
|
||||
this basic tonal gravity.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import TonedScale
|
||||
|
||||
scale = TonedScale(tonic="C4")["major"]
|
||||
|
||||
# The I-IV-V-I progression
|
||||
I = scale.triad(0) # C major — home
|
||||
IV = scale.triad(3) # F major — departure
|
||||
V = scale.triad(4) # G major — tension
|
||||
# I again # C major — resolution
|
||||
|
||||
The Dominant Seventh
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The most important chord in tonal music is the **dominant seventh** —
|
||||
the V7 chord. In C major, this is G-B-D-F. It contains:
|
||||
|
||||
- A **leading tone** (B) that pulls up to the tonic (C) by half step
|
||||
- A **tritone** (B-F) that wants to resolve inward (B→C, F→E)
|
||||
- The **dominant note** (G) that falls to the tonic by a fifth
|
||||
|
||||
This combination creates the strongest possible pull toward resolution.
|
||||
When you hear V7→I, you feel arrival.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import Chord, Tone
|
||||
|
||||
C4 = Tone.from_string("C4", system="western")
|
||||
G4 = Tone.from_string("G4", system="western")
|
||||
|
||||
g7 = Chord([G4, G4+4, G4+7, G4+10]) # G B D F
|
||||
g7.identify() # 'G dominant 7th'
|
||||
g7.tension['has_dominant_function'] # True
|
||||
g7.tension['tritones'] # 1
|
||||
|
||||
c_major = Chord([C4, C4+4, C4+7]) # C E G
|
||||
c_major.tension['score'] # 0.0 — fully resolved
|
||||
|
||||
Rhythm and Meter
|
||||
----------------
|
||||
|
||||
While PyTheory focuses on pitch, rhythm is the other half of music.
|
||||
|
||||
**Rhythm** is the pattern of durations. **Meter** is the recurring
|
||||
pattern of strong and weak beats that organizes rhythm.
|
||||
|
||||
- **4/4 time**: the most common meter. Strong-weak-medium-weak.
|
||||
Used in rock, pop, hip-hop, most Western music.
|
||||
- **3/4 time**: waltz time. Strong-weak-weak. A lilting, circular feel.
|
||||
- **6/8 time**: compound duple. Two groups of three. Irish jigs, many
|
||||
ballads.
|
||||
- **5/4 time**: asymmetric. "Take Five" by Dave Brubeck. Creates
|
||||
constant forward momentum because it never fully settles.
|
||||
- **7/8 time**: common in Balkan folk music. Often felt as 2+2+3 or
|
||||
3+2+2.
|
||||
|
||||
The Physics of Consonance
|
||||
-------------------------
|
||||
|
||||
Why do some intervals sound "good" and others "bad"? The answer lies
|
||||
in the physics of sound waves.
|
||||
|
||||
When two frequencies are related by a simple ratio (like 3:2 for a
|
||||
perfect fifth), their waveforms align regularly. The combined wave
|
||||
is smooth and periodic — the brain perceives this as consonant.
|
||||
|
||||
When two frequencies are related by a complex ratio (like 45:32 for
|
||||
a tritone), their waveforms rarely align. The combined wave is
|
||||
irregular and the brain perceives roughness — dissonance.
|
||||
|
||||
But consonance and dissonance are also cultural. The major third (5:4)
|
||||
was considered dissonant in medieval European music but consonant since
|
||||
the Renaissance. The tritone was forbidden in church music but is the
|
||||
foundation of blues and jazz. Indonesian gamelan embraces beating
|
||||
between paired instruments as a core aesthetic.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import Chord, Tone
|
||||
|
||||
C4 = Tone.from_string("C4", system="western")
|
||||
|
||||
# The overtone series explains why fifths sound consonant
|
||||
C4.overtones(6)
|
||||
# [261.63, 523.25, 784.88, 1046.50, 1308.13, 1569.75]
|
||||
# The 3rd harmonic (784.88) is very close to G5 (783.99)
|
||||
# — the fifth is "built into" the tone itself
|
||||
@@ -199,6 +199,62 @@ Equality checks note name and octave:
|
||||
>>> c4 == Tone(name="C", octave=4)
|
||||
True
|
||||
|
||||
The Overtone Series
|
||||
-------------------
|
||||
|
||||
Every tone you hear is actually a composite of many frequencies. When
|
||||
a string vibrates, it doesn't just vibrate as a whole — it also vibrates
|
||||
in halves, thirds, quarters, and so on, producing the **harmonic series**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> 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]
|
||||
|
||||
These harmonics correspond to musical intervals::
|
||||
|
||||
Harmonic Frequency Interval from fundamental
|
||||
1st 440 Hz Unison (A4)
|
||||
2nd 880 Hz Octave (A5)
|
||||
3rd 1320 Hz Octave + perfect 5th (E6)
|
||||
4th 1760 Hz Two octaves (A6)
|
||||
5th 2200 Hz Two octaves + major 3rd (C#7)
|
||||
6th 2640 Hz Two octaves + perfect 5th (E7)
|
||||
7th 3080 Hz Two octaves + minor 7th (≈G7, slightly flat)
|
||||
8th 3520 Hz Three octaves (A7)
|
||||
|
||||
The overtone series is why a perfect fifth sounds consonant — the 3rd
|
||||
harmonic of the lower note matches the 2nd harmonic of the upper note.
|
||||
It's also why the major triad (root, major 3rd, perfect 5th) feels
|
||||
"natural" — these intervals appear in the first 6 harmonics.
|
||||
|
||||
Different instruments emphasize different harmonics, which is why a
|
||||
violin and a flute playing the same note sound different. This quality
|
||||
is called **timbre**.
|
||||
|
||||
Enharmonic Equivalents
|
||||
----------------------
|
||||
|
||||
In equal temperament, C# and Db are the same pitch (they have the
|
||||
same frequency). They're called **enharmonic equivalents**. Which name
|
||||
you use depends on context:
|
||||
|
||||
- In the key of **D major** (2 sharps), you write **C#**
|
||||
- In the key of **Gb major** (6 flats), you write **Db**
|
||||
|
||||
The rule: each letter name should appear exactly once in a scale. The
|
||||
D major scale is D E F# G A B C# — not D E Gb G A B Db, even though
|
||||
F#=Gb and C#=Db.
|
||||
|
||||
PyTheory uses sharps by default (following the tone list ordering), but
|
||||
tones carry their enharmonic equivalents:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> Tone.from_tuple(("C#", "Db")).names()
|
||||
['C#', 'Db']
|
||||
|
||||
The Circle of Fifths
|
||||
--------------------
|
||||
|
||||
|
||||
@@ -27,6 +27,7 @@ Work with tones, scales, chords, and fretboards using a clean, Pythonic API.
|
||||
:caption: User Guide
|
||||
|
||||
guide/quickstart
|
||||
guide/theory
|
||||
guide/tones
|
||||
guide/scales
|
||||
guide/chords
|
||||
|
||||
Reference in New Issue
Block a user