From 4ab8be49a5082342fed38fd7b85aed6b54bf5f20 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 22 Mar 2026 06:29:16 -0400 Subject: [PATCH] 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) --- docs/_templates/layout.html | 18 +++ docs/guide/chords.rst | 57 ++++++++ docs/guide/scales.rst | 56 +++++++- docs/guide/theory.rst | 254 ++++++++++++++++++++++++++++++++++++ docs/guide/tones.rst | 56 ++++++++ docs/index.rst | 1 + 6 files changed, 441 insertions(+), 1 deletion(-) create mode 100644 docs/_templates/layout.html create mode 100644 docs/guide/theory.rst diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..1404cf7 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,18 @@ +{% extends "!layout.html" %} +{% block footer %} +{{ super() }} + +{% endblock %} diff --git a/docs/guide/chords.rst b/docs/guide/chords.rst index 90f52d5..c537ffb 100644 --- a/docs/guide/chords.rst +++ b/docs/guide/chords.rst @@ -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 --------------------- diff --git a/docs/guide/scales.rst b/docs/guide/scales.rst index 8069f9f..a9a070c 100644 --- a/docs/guide/scales.rst +++ b/docs/guide/scales.rst @@ -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'] diff --git a/docs/guide/theory.rst b/docs/guide/theory.rst new file mode 100644 index 0000000..8102c64 --- /dev/null +++ b/docs/guide/theory.rst @@ -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 diff --git a/docs/guide/tones.rst b/docs/guide/tones.rst index 587613d..d27a9cd 100644 --- a/docs/guide/tones.rst +++ b/docs/guide/tones.rst @@ -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 -------------------- diff --git a/docs/index.rst b/docs/index.rst index 26abb52..9225ddb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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