diff --git a/docs/conf.py b/docs/conf.py index 07f290d..ba47897 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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" diff --git a/docs/guide/chords.rst b/docs/guide/chords.rst index c537ffb..f1da1e8 100644 --- a/docs/guide/chords.rst +++ b/docs/guide/chords.rst @@ -1,7 +1,7 @@ Working with Chords =================== -A **chord** is two or more tones sounding simultaneously. Chords are the +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. @@ -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 `_** — 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 `_** — 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 `_**: - **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 `_** 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 `_ 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 `_**. 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 `_** 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 `_** 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 `_** (harmonics). The overtone series is nature's chord: it contains the octave, perfect fifth, perfect fourth, major third, and more, in that order. diff --git a/docs/guide/fretboard.rst b/docs/guide/fretboard.rst index b2152a8..49e37bb 100644 --- a/docs/guide/fretboard.rst +++ b/docs/guide/fretboard.rst @@ -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 `_ 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 `_ (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 `_, +`Drop D `_, and +`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 `_, +`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 `_ Example --------------- .. code-block:: python diff --git a/docs/guide/playback.rst b/docs/guide/playback.rst index 851cc7a..1946fcb 100644 --- a/docs/guide/playback.rst +++ b/docs/guide/playback.rst @@ -2,7 +2,7 @@ Audio Playback ============== PyTheory can synthesize and play tones and chords through your speakers -using basic waveform synthesis. +using basic `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 `_** (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 `_** — 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 `_). -- **Sawtooth wave** — contains all harmonics (both odd and even), +- **`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 `_ and analog synthesizers. -- **Triangle wave** — contains only odd harmonics, each at amplitude +- **`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." diff --git a/docs/guide/scales.rst b/docs/guide/scales.rst index a9a070c..e148934 100644 --- a/docs/guide/scales.rst +++ b/docs/guide/scales.rst @@ -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 `_:: 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 `_:: 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 `_ 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 `_** 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 `_** 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 `_** 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 `_** (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 `_** (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 `_** (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 `_** (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 `_** (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 `_** (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 `_ 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 `_** 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 `_** 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 — diff --git a/docs/guide/systems.rst b/docs/guide/systems.rst index 43005ce..3f159bb 100644 --- a/docs/guide/systems.rst +++ b/docs/guide/systems.rst @@ -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 `_** — the 10 parent scales from which `ragas `_ 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 `_). .. 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 `_ (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 `_** adds the "`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 `_ 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 `_** is a roughly equal 5-tone division of the octave, producing +an ethereal, floating quality. **`Pelog `_** is a 7-tone scale with unequal intervals, typically performed using 5-note subsets called *pathet*. .. code-block:: python diff --git a/docs/guide/theory.rst b/docs/guide/theory.rst index 8102c64..2b2cab4 100644 --- a/docs/guide/theory.rst +++ b/docs/guide/theory.rst @@ -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 `_, 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) +- **261.63 Hz**: `middle C `_ (C4) +- **440 Hz**: the `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 `_ 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 `_ 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 `_ +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 `_ +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 +- 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. +the `Pythagorean comma `_ +— the reason we need `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 `_ 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. +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: @@ -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 `_" 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 `_ (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#. +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: +`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):: @@ -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 `_ 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: +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#) +- `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:: +In any major key, the triads built on each +`scale degree `_ 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 `_: - **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 `_ +is exactly this pattern. Every "Louie Louie" and every +`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 `_ +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 +- 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. +This combination creates the strongest possible pull toward +`resolution `_. 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 `_ is the other half +of music. -**Rhythm** is the pattern of durations. **Meter** is the recurring +**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. +- `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 +- `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 +- 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. +in the physics of sound waves and the +`Plomp-Levelt `_ +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 `_ +— 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 `_ +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") + 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 `_ — Wikipedia overview +- `Equal temperament `_ — the modern tuning system +- `Circle of fifths `_ — key relationships +- `Chord progression `_ — common patterns +- `Voice leading `_ — smooth chord connections +- `Raga `_ — Indian melodic framework +- `Maqam `_ — Arabic melodic system +- `Gamelan `_ — Indonesian ensemble music +- `Blues `_ — the foundation of American popular music +- `Twelve-bar blues `_ — the most common blues form diff --git a/docs/guide/tones.rst b/docs/guide/tones.rst index d27a9cd..0198488 100644 --- a/docs/guide/tones.rst +++ b/docs/guide/tones.rst @@ -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 `_ (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 `_** — 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 `_** — 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 `_** (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 `_**: 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 `_**: 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 `_**: .. 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 `_**. 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 `_** 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: