mirror of
https://github.com/kennethreitz/pytheory.git
synced 2026-06-05 14:50:18 +00:00
Add Wikipedia links throughout docs, showcase dissonance API, update copyright
- Link key music theory terms to Wikipedia across all guide pages - Physics of Consonance section now demos .harmony, .dissonance, .tension, and .beat_frequencies with code examples - Copyright updated to 2026 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
+1
-1
@@ -8,7 +8,7 @@ sys.path.insert(0, os.path.abspath(".."))
|
||||
sys.modules["sounddevice"] = MagicMock()
|
||||
|
||||
project = "PyTheory"
|
||||
copyright = "2024, Kenneth Reitz"
|
||||
copyright = "2026, Kenneth Reitz"
|
||||
author = "Kenneth Reitz"
|
||||
release = "0.2.0"
|
||||
|
||||
|
||||
+10
-10
@@ -1,7 +1,7 @@
|
||||
Working with Chords
|
||||
===================
|
||||
|
||||
A **chord** is two or more tones sounding simultaneously. Chords are the
|
||||
A **`chord <https://en.wikipedia.org/wiki/Chord_(music)>`_** 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.
|
||||
|
||||
@@ -9,7 +9,7 @@ Chord Construction
|
||||
------------------
|
||||
|
||||
Chords are built by stacking **intervals** above a **root** note. The
|
||||
most common chord type is the **triad** — three notes built from
|
||||
most common chord type is the **`triad <https://en.wikipedia.org/wiki/Triad_(music)>`_** — three notes built from
|
||||
alternating scale degrees (root, 3rd, 5th).
|
||||
|
||||
The four triad types::
|
||||
@@ -19,7 +19,7 @@ The four triad types::
|
||||
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
|
||||
Adding a 7th creates a **`seventh chord <https://en.wikipedia.org/wiki/Seventh_chord>`_** — the foundation of jazz
|
||||
harmony::
|
||||
|
||||
Dominant 7th root + 4 + 7 + 10 Bluesy, wants to resolve (G7)
|
||||
@@ -31,7 +31,7 @@ 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**:
|
||||
When a different chord tone is in the bass, the chord is **`inverted <https://en.wikipedia.org/wiki/Inversion_(music)>`_**:
|
||||
|
||||
- **Root position**: C E G (root in bass)
|
||||
- **First inversion**: E G C (3rd in bass) — notated C/E
|
||||
@@ -61,7 +61,7 @@ For seventh chords, there's also **third inversion** (7th in bass):
|
||||
Extended Chords
|
||||
---------------
|
||||
|
||||
Beyond seventh chords, jazz harmony builds **extended chords** by
|
||||
Beyond seventh chords, jazz harmony builds **`extended chords <https://en.wikipedia.org/wiki/Extended_chord>`_** by
|
||||
continuing to stack thirds:
|
||||
|
||||
- **9th chord**: adds the 9th (= 2nd, one octave up)
|
||||
@@ -196,9 +196,9 @@ Tritone 45:32 Waves rarely align
|
||||
Dissonance Score
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``dissonance`` property uses the **Plomp-Levelt roughness model**
|
||||
The ``dissonance`` property uses the **Plomp-Levelt `roughness <https://en.wikipedia.org/wiki/Roughness_(psychoacoustics)>`_ model**
|
||||
(1965). When two frequencies are close together, their sound waves
|
||||
interfere and produce rapid amplitude fluctuations called **beating**.
|
||||
interfere and produce rapid amplitude fluctuations called **`beating <https://en.wikipedia.org/wiki/Beat_(acoustics)>`_**.
|
||||
This beating is perceived as roughness — the physiological basis of
|
||||
dissonance.
|
||||
|
||||
@@ -268,7 +268,7 @@ against 17 known chord types (triads, 7ths, 9ths, sus, power chords).
|
||||
Harmonic Analysis
|
||||
-----------------
|
||||
|
||||
**Roman numeral analysis** labels each chord by its function within a
|
||||
**`Roman numeral analysis <https://en.wikipedia.org/wiki/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).
|
||||
@@ -320,7 +320,7 @@ quantifies this based on:
|
||||
Voice Leading
|
||||
-------------
|
||||
|
||||
**Voice leading** is the art of connecting chords smoothly. Instead of
|
||||
**`Voice leading <https://en.wikipedia.org/wiki/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.
|
||||
@@ -338,7 +338,7 @@ The Overtone Series
|
||||
-------------------
|
||||
|
||||
Every musical tone is actually a stack of frequencies — the
|
||||
**fundamental** plus its **overtones** (harmonics). The overtone series
|
||||
**fundamental** plus its **`overtones <https://en.wikipedia.org/wiki/Overtone>`_** (harmonics). The overtone series
|
||||
is nature's chord: it contains the octave, perfect fifth, perfect
|
||||
fourth, major third, and more, in that order.
|
||||
|
||||
|
||||
@@ -7,11 +7,11 @@ tuning and generates chord fingerings.
|
||||
How Frets Work
|
||||
--------------
|
||||
|
||||
Each fret on a guitar (or any fretted instrument) raises the pitch by
|
||||
Each `fret <https://en.wikipedia.org/wiki/Fret>`_ on a guitar (or any fretted instrument) raises the pitch by
|
||||
exactly **one semitone**. The open string is fret 0; fret 1 is one
|
||||
semitone up, fret 2 is two semitones up, and so on.
|
||||
|
||||
Standard guitar tuning (high to low)::
|
||||
`Standard guitar tuning <https://en.wikipedia.org/wiki/Guitar_tunings>`_ (high to low)::
|
||||
|
||||
String 1: E4 (highest)
|
||||
String 2: B3
|
||||
@@ -39,6 +39,11 @@ Preset Tunings
|
||||
Alternate Guitar Tunings
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
PyTheory supports several common alternate tunings, including
|
||||
`open tunings <https://en.wikipedia.org/wiki/Open_tuning>`_,
|
||||
`Drop D <https://en.wikipedia.org/wiki/Drop_D_tuning>`_, and
|
||||
`DADGAD <https://en.wikipedia.org/wiki/DADGAD>`_:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
# Built-in alternate tunings
|
||||
@@ -56,7 +61,8 @@ Alternate Guitar Tunings
|
||||
Custom Instruments
|
||||
------------------
|
||||
|
||||
Any fretted instrument can be modeled:
|
||||
Any fretted instrument can be modeled, including `banjo <https://en.wikipedia.org/wiki/Banjo>`_,
|
||||
`mandolin <https://en.wikipedia.org/wiki/Mandolin>`_, and more:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -138,7 +144,7 @@ Generate fingerings for every chord at once:
|
||||
for name, fingering in chart.items():
|
||||
print(f"{name:6s} {fingering}")
|
||||
|
||||
Ukulele Example
|
||||
`Ukulele <https://en.wikipedia.org/wiki/Ukulele>`_ Example
|
||||
---------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -2,7 +2,7 @@ Audio Playback
|
||||
==============
|
||||
|
||||
PyTheory can synthesize and play tones and chords through your speakers
|
||||
using basic waveform synthesis.
|
||||
using basic `waveform <https://en.wikipedia.org/wiki/Waveform>`_ synthesis.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -37,19 +37,19 @@ Playing a Chord
|
||||
Waveform Types
|
||||
--------------
|
||||
|
||||
The waveform shape determines the **timbre** (tonal color) of the sound.
|
||||
The waveform shape determines the **`timbre <https://en.wikipedia.org/wiki/Timbre>`_** (tonal color) of the sound.
|
||||
Different waveforms contain different combinations of **harmonics** —
|
||||
integer multiples of the fundamental frequency.
|
||||
|
||||
- **Sine wave** — the purest tone. Contains only the fundamental
|
||||
- **`Sine wave <https://en.wikipedia.org/wiki/Sine_wave>`_** — the purest tone. Contains only the fundamental
|
||||
frequency with no harmonics. Sounds smooth, clear, and "electronic."
|
||||
This is the building block of all other waveforms (Fourier's theorem).
|
||||
This is the building block of all other waveforms (`Fourier's theorem <https://en.wikipedia.org/wiki/Fourier_series>`_).
|
||||
|
||||
- **Sawtooth wave** — contains all harmonics (both odd and even),
|
||||
- **`Sawtooth wave <https://en.wikipedia.org/wiki/Sawtooth_wave>`_** — contains all harmonics (both odd and even),
|
||||
each at amplitude 1/n. Sounds bright, buzzy, and aggressive.
|
||||
Named for its shape. Used extensively in analog synthesizers.
|
||||
Named for its shape. Used extensively in `additive synthesis <https://en.wikipedia.org/wiki/Additive_synthesis>`_ and analog synthesizers.
|
||||
|
||||
- **Triangle wave** — contains only odd harmonics, each at amplitude
|
||||
- **`Triangle wave <https://en.wikipedia.org/wiki/Triangle_wave>`_** — contains only odd harmonics, each at amplitude
|
||||
1/n². Sounds softer and more mellow than sawtooth — somewhere between
|
||||
sine and sawtooth. Often described as "woody" or "hollow."
|
||||
|
||||
|
||||
+15
-15
@@ -13,13 +13,13 @@ Every scale is defined by its **interval pattern** — the sequence of
|
||||
whole steps (W = 2 semitones) and half steps (H = 1 semitone) between
|
||||
consecutive tones.
|
||||
|
||||
The major scale::
|
||||
The `major scale <https://en.wikipedia.org/wiki/Major_scale>`_::
|
||||
|
||||
W W H W W W H
|
||||
C D E F G A B C
|
||||
2 2 1 2 2 2 1 ← semitones between each note
|
||||
|
||||
The natural minor scale::
|
||||
The `natural minor scale <https://en.wikipedia.org/wiki/Minor_scale>`_::
|
||||
|
||||
W H W W H W W
|
||||
C D Eb F G Ab Bb C
|
||||
@@ -46,9 +46,9 @@ Use :class:`~pytheory.scales.TonedScale` to generate scales in any key:
|
||||
Major and Minor
|
||||
---------------
|
||||
|
||||
The **major scale** (Ionian mode) is the foundation of Western tonal
|
||||
The **major scale** (`Ionian <https://en.wikipedia.org/wiki/Ionian_mode>`_ mode) is the foundation of Western tonal
|
||||
music. Its pattern of whole and half steps creates a bright, resolved
|
||||
sound. Every major key has a **relative minor** that shares the same
|
||||
sound. Every major key has a **`relative minor <https://en.wikipedia.org/wiki/Relative_key>`_** that shares the same
|
||||
notes but starts from the 6th degree:
|
||||
|
||||
- C major → A minor (both use only white keys)
|
||||
@@ -63,7 +63,7 @@ notes but starts from the 6th degree:
|
||||
# Same notes, different starting point
|
||||
set(c_major.note_names) == set(a_minor.note_names) # True
|
||||
|
||||
The **harmonic minor** raises the 7th degree of the natural minor,
|
||||
The **`harmonic minor <https://en.wikipedia.org/wiki/Harmonic_minor_scale>`_** raises the 7th degree of the natural minor,
|
||||
creating an augmented 2nd interval (3 semitones) between the 6th and
|
||||
7th degrees. This gives it a distinctive "Middle Eastern" or "classical"
|
||||
sound and provides the leading tone needed for dominant harmony::
|
||||
@@ -75,7 +75,7 @@ sound and provides the leading tone needed for dominant harmony::
|
||||
Modes
|
||||
-----
|
||||
|
||||
The seven **modes** of the major scale are rotations of the same interval
|
||||
The seven **`modes <https://en.wikipedia.org/wiki/Mode_(music)>`_** of the major scale are rotations of the same interval
|
||||
pattern, each starting from a different degree. Each mode has a distinct
|
||||
emotional character:
|
||||
|
||||
@@ -87,32 +87,32 @@ emotional character:
|
||||
|
||||
c["ionian"] # C D E F G A B C
|
||||
|
||||
**Dorian** (ii) — minor with a raised 6th. Jazzy, soulful (So What,
|
||||
**`Dorian <https://en.wikipedia.org/wiki/Dorian_mode>`_** (ii) — minor with a raised 6th. Jazzy, soulful (So What,
|
||||
Scarborough Fair)::
|
||||
|
||||
c["dorian"] # C D Eb F G A Bb C
|
||||
|
||||
**Phrygian** (iii) — minor with a flat 2nd. Spanish, flamenco, dark
|
||||
**`Phrygian <https://en.wikipedia.org/wiki/Phrygian_mode>`_** (iii) — minor with a flat 2nd. Spanish, flamenco, dark
|
||||
(White Rabbit)::
|
||||
|
||||
c["phrygian"] # C Db Eb F G Ab Bb C
|
||||
|
||||
**Lydian** (IV) — major with a raised 4th. Dreamy, floating, ethereal
|
||||
**`Lydian <https://en.wikipedia.org/wiki/Lydian_mode>`_** (IV) — major with a raised 4th. Dreamy, floating, ethereal
|
||||
(The Simpsons theme, Flying by ET)::
|
||||
|
||||
c["lydian"] # C D E F# G A B C
|
||||
|
||||
**Mixolydian** (V) — major with a flat 7th. Bluesy, rock, dominant
|
||||
**`Mixolydian <https://en.wikipedia.org/wiki/Mixolydian_mode>`_** (V) — major with a flat 7th. Bluesy, rock, dominant
|
||||
(Norwegian Wood, Sweet Home Alabama)::
|
||||
|
||||
c["mixolydian"] # C D E F G A Bb C
|
||||
|
||||
**Aeolian** (vi) — the natural minor scale. Sad, dark, introspective
|
||||
**`Aeolian <https://en.wikipedia.org/wiki/Aeolian_mode>`_** (vi) — the natural minor scale. Sad, dark, introspective
|
||||
(Stairway to Heaven, Losing My Religion)::
|
||||
|
||||
c["aeolian"] # C D Eb F G Ab Bb C
|
||||
|
||||
**Locrian** (vii) — minor with flat 2nd and flat 5th. Unstable,
|
||||
**`Locrian <https://en.wikipedia.org/wiki/Locrian_mode>`_** (vii) — minor with flat 2nd and flat 5th. Unstable,
|
||||
rarely used as a home key (used in metal and jazz over diminished
|
||||
chords)::
|
||||
|
||||
@@ -167,7 +167,7 @@ Scales are iterable and support ``len()`` and ``in``:
|
||||
Building Chords from Scales
|
||||
----------------------------
|
||||
|
||||
**Diatonic harmony** builds chords by stacking every other note of the
|
||||
**`Diatonic <https://en.wikipedia.org/wiki/Diatonic_and_chromatic>`_ harmony** builds chords by stacking every other note of the
|
||||
scale. A **triad** takes the 1st, 3rd, and 5th; a **seventh chord** adds
|
||||
the 7th.
|
||||
|
||||
@@ -218,7 +218,7 @@ Some of the most-used chord progressions in Western music:
|
||||
The 12-Bar Blues
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
The **12-bar blues** is the most influential chord progression in
|
||||
The **`12-bar blues <https://en.wikipedia.org/wiki/Twelve-bar_blues>`_** is the most influential chord progression in
|
||||
American music. It's 12 measures long and uses only three chords
|
||||
(I, IV, V)::
|
||||
|
||||
@@ -249,7 +249,7 @@ 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
|
||||
A minor). Two scales are **`parallel <https://en.wikipedia.org/wiki/Parallel_key>`_** 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 —
|
||||
|
||||
@@ -28,7 +28,7 @@ Indian Classical (Hindustani)
|
||||
-----------------------------
|
||||
|
||||
The Hindustani system uses **swaras** (Sa, Re, Ga, Ma, Pa, Dha, Ni) and
|
||||
organizes scales into **thaats** — the 10 parent scales from which ragas
|
||||
organizes scales into **`thaats <https://en.wikipedia.org/wiki/Thaat>`_** — the 10 parent scales from which `ragas <https://en.wikipedia.org/wiki/Raga>`_
|
||||
are derived.
|
||||
|
||||
.. code-block:: python
|
||||
@@ -60,7 +60,7 @@ Arabic Maqam
|
||||
------------
|
||||
|
||||
The Arabic system uses **solfège-based names** (Do, Re, Mi, Fa, Sol, La, Si)
|
||||
and organizes scales into **maqamat** (plural of maqam).
|
||||
and organizes scales into **maqamat** (plural of `maqam <https://en.wikipedia.org/wiki/Maqam>`_).
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -120,11 +120,11 @@ Blues and Pentatonic
|
||||
-------------------
|
||||
|
||||
The blues system provides the scales foundational to blues, rock, jazz,
|
||||
and folk music worldwide. Pentatonic scales (5 notes) are the oldest
|
||||
and folk music worldwide. `Pentatonic scales <https://en.wikipedia.org/wiki/Pentatonic_scale>`_ (5 notes) are the oldest
|
||||
known musical scales, found independently in cultures across every
|
||||
continent.
|
||||
|
||||
The **blues scale** adds the "blue note" (flat 5th / sharp 4th) to the
|
||||
The **`blues scale <https://en.wikipedia.org/wiki/Blues_scale>`_** adds the "`blue note <https://en.wikipedia.org/wiki/Blue_note>`_" (flat 5th / sharp 4th) to the
|
||||
minor pentatonic — this chromatic passing tone is the defining sound
|
||||
of the blues.
|
||||
|
||||
@@ -158,13 +158,13 @@ minor (Dorian — the jazz minor sound)
|
||||
Javanese Gamelan
|
||||
----------------
|
||||
|
||||
The gamelan system approximates the scales of the Javanese and Balinese
|
||||
The `gamelan <https://en.wikipedia.org/wiki/Gamelan>`_ system approximates the scales of the Javanese and Balinese
|
||||
gamelan orchestra in 12-tone equal temperament. True gamelan tuning is
|
||||
unique to each ensemble and does not conform to Western intonation —
|
||||
these are the closest 12-TET approximations.
|
||||
|
||||
**Slendro** is a roughly equal 5-tone division of the octave, producing
|
||||
an ethereal, floating quality. **Pelog** is a 7-tone scale with unequal
|
||||
**`Slendro <https://en.wikipedia.org/wiki/Slendro>`_** is a roughly equal 5-tone division of the octave, producing
|
||||
an ethereal, floating quality. **`Pelog <https://en.wikipedia.org/wiki/Pelog>`_** is a 7-tone scale with unequal
|
||||
intervals, typically performed using 5-note subsets called *pathet*.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
+146
-73
@@ -9,41 +9,46 @@ 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.
|
||||
speed of this vibration — measured in cycles per second
|
||||
(`Hertz <https://en.wikipedia.org/wiki/Hertz>`_, Hz) — determines the
|
||||
`pitch <https://en.wikipedia.org/wiki/Pitch_(music)>`_ 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)
|
||||
- **261.63 Hz**: `middle C <https://en.wikipedia.org/wiki/C_(musical_note)#Middle_C>`_ (C4)
|
||||
- **440 Hz**: the `concert pitch <https://en.wikipedia.org/wiki/Concert_pitch>`_ tuning standard A (A4)
|
||||
- **4186 Hz**: the highest C on a piano (C8)
|
||||
- **20,000 Hz**: the upper limit of human hearing
|
||||
- **20,000 Hz**: the upper limit of `human hearing <https://en.wikipedia.org/wiki/Hearing_range>`_
|
||||
|
||||
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.
|
||||
`octave <https://en.wikipedia.org/wiki/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 Western `chromatic scale <https://en.wikipedia.org/wiki/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:
|
||||
The `harmonic series <https://en.wikipedia.org/wiki/Harmonic_series_(music)>`_
|
||||
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 <https://en.wikipedia.org/wiki/Consonance_and_dissonance>`_:
|
||||
|
||||
- 2:1 = octave (the most fundamental)
|
||||
- 3:2 = perfect fifth
|
||||
- 4:3 = perfect fourth
|
||||
- 5:4 = major third
|
||||
- 6:5 = minor third
|
||||
- 2:1 = `octave <https://en.wikipedia.org/wiki/Octave>`_ (the most fundamental)
|
||||
- 3:2 = `perfect fifth <https://en.wikipedia.org/wiki/Perfect_fifth>`_
|
||||
- 4:3 = `perfect fourth <https://en.wikipedia.org/wiki/Perfect_fourth>`_
|
||||
- 5:4 = `major third <https://en.wikipedia.org/wiki/Major_third>`_
|
||||
- 6:5 = `minor third <https://en.wikipedia.org/wiki/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.
|
||||
the `Pythagorean comma <https://en.wikipedia.org/wiki/Pythagorean_comma>`_
|
||||
— the reason we need `temperament <https://en.wikipedia.org/wiki/Musical_temperament>`_.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -54,16 +59,20 @@ the **Pythagorean comma** — the reason we need temperament.
|
||||
[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.
|
||||
Other cultures divide the octave differently: Indonesian
|
||||
`gamelan <https://en.wikipedia.org/wiki/Gamelan>`_ uses 5 or 7 unequal
|
||||
divisions; Indian classical music theoretically has 22
|
||||
`shrutis <https://en.wikipedia.org/wiki/Shruti_(music)>`_ (microtones);
|
||||
Arabic `maqam <https://en.wikipedia.org/wiki/Maqam>`_ uses
|
||||
`quarter-tones <https://en.wikipedia.org/wiki/Quarter_tone>`_.
|
||||
|
||||
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.
|
||||
An `interval <https://en.wikipedia.org/wiki/Interval_(music)>`_ 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:
|
||||
|
||||
@@ -79,25 +88,29 @@ Every interval has two properties:
|
||||
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 "`perfect <https://en.wikipedia.org/wiki/Perfect_fifth>`_" 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.
|
||||
The `tritone <https://en.wikipedia.org/wiki/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 <https://en.wikipedia.org/wiki/Dominant_(music)>`_
|
||||
and the `blues <https://en.wikipedia.org/wiki/Blue_note>`_.
|
||||
|
||||
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#.
|
||||
A `key <https://en.wikipedia.org/wiki/Key_(music)>`_ 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:
|
||||
`Key signatures <https://en.wikipedia.org/wiki/Key_signature>`_ tell
|
||||
you which notes are sharped or flatted throughout a piece. They follow
|
||||
the `circle of fifths <https://en.wikipedia.org/wiki/Circle_of_fifths>`_:
|
||||
|
||||
**Sharp keys** (add one sharp per step clockwise)::
|
||||
|
||||
@@ -123,19 +136,23 @@ 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).
|
||||
`Harmony <https://en.wikipedia.org/wiki/Harmony>`_ is the art of
|
||||
combining tones simultaneously. While
|
||||
`melody <https://en.wikipedia.org/wiki/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:
|
||||
The simplest harmony is the `triad <https://en.wikipedia.org/wiki/Triad_(music)>`_
|
||||
— three notes built by stacking `thirds <https://en.wikipedia.org/wiki/Third_(music)>`_.
|
||||
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#)
|
||||
- `Diminished triad <https://en.wikipedia.org/wiki/Diminished_triad>`_ = minor 3rd + minor 3rd (e.g. B-D-F)
|
||||
- `Augmented triad <https://en.wikipedia.org/wiki/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::
|
||||
In any major key, the triads built on each
|
||||
`scale degree <https://en.wikipedia.org/wiki/Degree_(music)>`_ always
|
||||
follow the same pattern::
|
||||
|
||||
Degree Quality Function
|
||||
I Major Tonic (home)
|
||||
@@ -152,15 +169,18 @@ sonatas, jazz standards, and church hymns all derive from it.
|
||||
Functional Harmony
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Chords don't just have names — they have **functions**:
|
||||
Chords don't just have names — they have
|
||||
`functions <https://en.wikipedia.org/wiki/Function_(music)>`_:
|
||||
|
||||
- **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
|
||||
(tonic → subdominant → dominant → tonic). The classic
|
||||
`I-IV-V-I <https://en.wikipedia.org/wiki/I%E2%80%93IV%E2%80%93V%E2%80%93I>`_
|
||||
is exactly this pattern. Every "Louie Louie" and every
|
||||
`Bach chorale <https://en.wikipedia.org/wiki/Bach_chorale>`_ follows
|
||||
this basic tonal gravity.
|
||||
|
||||
.. code-block:: python
|
||||
@@ -178,14 +198,16 @@ this basic tonal gravity.
|
||||
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:
|
||||
The most important chord in `tonal music <https://en.wikipedia.org/wiki/Tonality>`_
|
||||
is the `dominant seventh <https://en.wikipedia.org/wiki/Dominant_seventh_chord>`_
|
||||
— 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
|
||||
- A `leading tone <https://en.wikipedia.org/wiki/Leading-tone>`_ (B) that pulls up to the tonic (C) by half step
|
||||
- A `tritone <https://en.wikipedia.org/wiki/Tritone>`_ (B-F) that wants to resolve inward (B→C, F→E)
|
||||
- The `dominant note <https://en.wikipedia.org/wiki/Dominant_(music)>`_ (G) that falls to the tonic by a fifth
|
||||
|
||||
This combination creates the strongest possible pull toward resolution.
|
||||
This combination creates the strongest possible pull toward
|
||||
`resolution <https://en.wikipedia.org/wiki/Resolution_(music)>`_.
|
||||
When you hear V7→I, you feel arrival.
|
||||
|
||||
.. code-block:: python
|
||||
@@ -206,26 +228,32 @@ When you hear V7→I, you feel arrival.
|
||||
Rhythm and Meter
|
||||
----------------
|
||||
|
||||
While PyTheory focuses on pitch, rhythm is the other half of music.
|
||||
While PyTheory focuses on pitch,
|
||||
`rhythm <https://en.wikipedia.org/wiki/Rhythm>`_ is the other half
|
||||
of music.
|
||||
|
||||
**Rhythm** is the pattern of durations. **Meter** is the recurring
|
||||
**Rhythm** is the pattern of durations.
|
||||
`Meter <https://en.wikipedia.org/wiki/Metre_(music)>`_ is the recurring
|
||||
pattern of strong and weak beats that organizes rhythm.
|
||||
|
||||
- **4/4 time**: the most common meter. Strong-weak-medium-weak.
|
||||
- `4/4 time <https://en.wikipedia.org/wiki/Time_signature#Simple_time_signatures>`_: 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
|
||||
- `3/4 time <https://en.wikipedia.org/wiki/Triple_metre>`_: waltz time. Strong-weak-weak. A lilting, circular feel.
|
||||
- `6/8 time <https://en.wikipedia.org/wiki/Compound_meter_(music)>`_: 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
|
||||
- 5/4 time: asymmetric. "`Take Five <https://en.wikipedia.org/wiki/Take_Five>`_"
|
||||
by Dave Brubeck. Creates constant forward momentum because it never
|
||||
fully settles.
|
||||
- `7/8 time <https://en.wikipedia.org/wiki/Additive_rhythm_and_divisive_rhythm>`_: 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.
|
||||
in the physics of sound waves and the
|
||||
`Plomp-Levelt <https://en.wikipedia.org/wiki/Consonance_and_dissonance#Physiological_basis>`_
|
||||
model of sensory dissonance.
|
||||
|
||||
When two frequencies are related by a simple ratio (like 3:2 for a
|
||||
perfect fifth), their waveforms align regularly. The combined wave
|
||||
@@ -233,22 +261,67 @@ 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.
|
||||
irregular and the brain perceives
|
||||
`roughness <https://en.wikipedia.org/wiki/Roughness_(psychoacoustics)>`_
|
||||
— 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.
|
||||
But `consonance and dissonance <https://en.wikipedia.org/wiki/Consonance_and_dissonance>`_
|
||||
are also cultural. The
|
||||
`major third <https://en.wikipedia.org/wiki/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 <https://en.wikipedia.org/wiki/Beat_(acoustics)>`_ between
|
||||
paired instruments as a core aesthetic.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pytheory import Chord, Tone
|
||||
|
||||
C4 = Tone.from_string("C4", system="western")
|
||||
E4 = Tone.from_string("E4", system="western")
|
||||
G4 = Tone.from_string("G4", system="western")
|
||||
|
||||
# The overtone series explains why fifths sound consonant
|
||||
# The overtone series — the fifth is "built into" every tone
|
||||
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
|
||||
# 3rd harmonic (784.88) ≈ G5 (783.99) — a perfect fifth
|
||||
|
||||
# Consonance: simple frequency ratios score high
|
||||
fifth = Chord([C4, G4]) # 3:2 ratio
|
||||
tritone = Chord([C4, C4 + 6]) # 45:32 ratio
|
||||
fifth.harmony > tritone.harmony # True
|
||||
|
||||
# Dissonance: Plomp-Levelt roughness model
|
||||
# An octave has low roughness (frequencies far apart)
|
||||
# A major 3rd has more roughness (closer frequencies)
|
||||
octave = Chord([C4, C4 + 12])
|
||||
third = Chord([C4, E4])
|
||||
octave.dissonance < third.dissonance # True
|
||||
|
||||
# Tension: tritones and dominant function
|
||||
c_major = Chord([C4, E4, G4])
|
||||
c_major.tension['score'] # 0.0 — fully resolved
|
||||
|
||||
g7 = Chord([G4, G4+4, G4+7, G4+10]) # G dominant 7th
|
||||
g7.tension['score'] # 0.6 — wants to resolve
|
||||
g7.tension['tritones'] # 1 (B-F)
|
||||
g7.tension['has_dominant_function'] # True
|
||||
|
||||
# Beat frequencies — the pulsing between close pitches
|
||||
g7.beat_frequencies
|
||||
# [(tone_a, tone_b, hz), ...] sorted by frequency
|
||||
|
||||
Further Reading
|
||||
---------------
|
||||
|
||||
- `Music theory <https://en.wikipedia.org/wiki/Music_theory>`_ — Wikipedia overview
|
||||
- `Equal temperament <https://en.wikipedia.org/wiki/Equal_temperament>`_ — the modern tuning system
|
||||
- `Circle of fifths <https://en.wikipedia.org/wiki/Circle_of_fifths>`_ — key relationships
|
||||
- `Chord progression <https://en.wikipedia.org/wiki/Chord_progression>`_ — common patterns
|
||||
- `Voice leading <https://en.wikipedia.org/wiki/Voice_leading>`_ — smooth chord connections
|
||||
- `Raga <https://en.wikipedia.org/wiki/Raga>`_ — Indian melodic framework
|
||||
- `Maqam <https://en.wikipedia.org/wiki/Maqam>`_ — Arabic melodic system
|
||||
- `Gamelan <https://en.wikipedia.org/wiki/Gamelan>`_ — Indonesian ensemble music
|
||||
- `Blues <https://en.wikipedia.org/wiki/Blues>`_ — the foundation of American popular music
|
||||
- `Twelve-bar blues <https://en.wikipedia.org/wiki/Twelve-bar_blues>`_ — the most common blues form
|
||||
|
||||
@@ -2,7 +2,7 @@ Working with Tones
|
||||
==================
|
||||
|
||||
A :class:`~pytheory.tones.Tone` represents a single musical note, optionally
|
||||
with an octave number in scientific pitch notation (e.g. C4 = middle C).
|
||||
with an octave number in `scientific pitch notation <https://en.wikipedia.org/wiki/Scientific_pitch_notation>`_ (e.g. C4 = middle C).
|
||||
|
||||
What is a Tone?
|
||||
---------------
|
||||
@@ -16,7 +16,7 @@ The 12 chromatic tones are::
|
||||
|
||||
C C#/Db D D#/Eb E F F#/Gb G G#/Ab A A#/Bb B
|
||||
|
||||
Notes with two names (like C# and Db) are **enharmonic equivalents** —
|
||||
Notes with two names (like C# and Db) are **`enharmonic equivalents <https://en.wikipedia.org/wiki/Enharmonic>`_** —
|
||||
different names for the same pitch. Whether you call it C# or Db depends
|
||||
on the musical context (key signature, harmonic function).
|
||||
|
||||
@@ -32,7 +32,7 @@ pitch notation**, where the octave number increments at C::
|
||||
|
||||
Key reference points:
|
||||
|
||||
- **A4 = 440 Hz** — the international tuning standard (ISO 16)
|
||||
- **`A4 = 440 Hz <https://en.wikipedia.org/wiki/A440_(pitch_standard)>`_** — the international tuning standard (ISO 16)
|
||||
- **C4 = 261.63 Hz** — middle C on the piano
|
||||
- **A0 = 27.5 Hz** — the lowest A on a standard piano
|
||||
- **C8 = 4186 Hz** — the highest C on a standard piano
|
||||
@@ -96,17 +96,17 @@ Temperament
|
||||
Different temperaments produce slightly different frequencies for the
|
||||
same note name:
|
||||
|
||||
- **Equal temperament** (default): Every semitone has an identical
|
||||
- **`Equal temperament <https://en.wikipedia.org/wiki/Equal_temperament>`_** (default): Every semitone has an identical
|
||||
frequency ratio of 2^(1/12). This is the modern standard — it allows
|
||||
free modulation between all keys but no interval is acoustically
|
||||
"pure" except the octave.
|
||||
|
||||
- **Pythagorean temperament**: Built entirely from pure perfect fifths
|
||||
- **`Pythagorean temperament <https://en.wikipedia.org/wiki/Pythagorean_tuning>`_**: Built entirely from pure perfect fifths
|
||||
(3:2 ratio). Produces beatless fifths but introduces the "Pythagorean
|
||||
comma" — a small discrepancy when 12 fifths don't quite equal 7
|
||||
octaves. Used in medieval European music.
|
||||
|
||||
- **Quarter-comma meantone**: Tunes major thirds to the pure ratio of
|
||||
- **`Quarter-comma meantone <https://en.wikipedia.org/wiki/Quarter-comma_meantone>`_**: Tunes major thirds to the pure ratio of
|
||||
5:4, distributing the resulting error across the fifths. Dominant in
|
||||
Renaissance and Baroque music (15th–18th century). Sounds beautiful
|
||||
in closely related keys but "wolf intervals" make distant keys
|
||||
@@ -204,7 +204,7 @@ 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**:
|
||||
in halves, thirds, quarters, and so on, producing the **`harmonic series <https://en.wikipedia.org/wiki/Harmonic_series_(music)>`_**:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@@ -231,7 +231,7 @@ It's also why the major triad (root, major 3rd, perfect 5th) feels
|
||||
|
||||
Different instruments emphasize different harmonics, which is why a
|
||||
violin and a flute playing the same note sound different. This quality
|
||||
is called **timbre**.
|
||||
is called **`timbre <https://en.wikipedia.org/wiki/Timbre>`_**.
|
||||
|
||||
Enharmonic Equivalents
|
||||
----------------------
|
||||
@@ -258,7 +258,7 @@ tones carry their enharmonic equivalents:
|
||||
The Circle of Fifths
|
||||
--------------------
|
||||
|
||||
The **circle of fifths** is the most important diagram in Western music
|
||||
The **`circle of fifths <https://en.wikipedia.org/wiki/Circle_of_fifths>`_** is the most important diagram in Western music
|
||||
theory. Starting from any note and ascending by perfect fifths (7
|
||||
semitones), you pass through all 12 chromatic tones before returning
|
||||
to the starting note:
|
||||
|
||||
Reference in New Issue
Block a user