mirror of
https://github.com/kennethreitz/pytheory.git
synced 2026-06-05 23:00:20 +00:00
kennethreitz
eba299d406
Breaks the single code block into focused sections: Tones, Scales, Keys and Chords, Guitar Fingerings, Audio Playback, and Command Line. Adds installation notes for PortAudio, shows from_frequency/from_midi, enharmonics, Key class, Chord convenience constructors, tab output, WAV export, and CLI commands. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
193 lines
4.9 KiB
ReStructuredText
193 lines
4.9 KiB
ReStructuredText
Quickstart
|
|
==========
|
|
|
|
Installation
|
|
------------
|
|
|
|
::
|
|
|
|
$ pip install pytheory
|
|
|
|
For audio playback, you'll also need `PortAudio <http://www.portaudio.com/>`_:
|
|
|
|
- macOS: ``brew install portaudio``
|
|
- Ubuntu: ``apt install libportaudio2``
|
|
- Windows: included with the ``sounddevice`` package
|
|
|
|
Tones
|
|
-----
|
|
|
|
A :class:`~pytheory.tones.Tone` is a single musical note:
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Tone
|
|
|
|
# Create tones — sharps and flats both work
|
|
a4 = Tone.from_string("A4", system="western")
|
|
a4.frequency # 440.0 Hz — the tuning standard
|
|
|
|
c4 = Tone.from_string("C4", system="western")
|
|
c4.midi # 60 — middle C
|
|
|
|
# From a frequency or MIDI number
|
|
Tone.from_frequency(440) # <Tone A4>
|
|
Tone.from_midi(60) # <Tone C4>
|
|
|
|
# Tone arithmetic
|
|
c4 + 4 # <Tone E4> — major third up
|
|
c4 + 7 # <Tone G4> — perfect fifth up
|
|
|
|
# Interval between two tones
|
|
g4 = c4 + 7
|
|
g4 - c4 # 7 semitones
|
|
c4.interval_to(g4) # 'perfect 5th'
|
|
|
|
# Enharmonics
|
|
Tone.from_string("C#4", system="western").enharmonic # 'Db'
|
|
|
|
Scales
|
|
------
|
|
|
|
Build scales in any key and mode:
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import TonedScale
|
|
|
|
c = TonedScale(tonic="C4")
|
|
|
|
c["major"].note_names
|
|
# ['C', 'D', 'E', 'F', 'G', 'A', 'B', 'C']
|
|
|
|
c["minor"].note_names
|
|
# ['C', 'D', 'D#', 'F', 'G', 'G#', 'A#', 'C']
|
|
|
|
c["dorian"].note_names
|
|
# ['C', 'D', 'D#', 'F', 'G', 'A', 'A#', 'C']
|
|
|
|
# Access scale degrees by name or numeral
|
|
major = c["major"]
|
|
major["tonic"] # C4
|
|
major["dominant"] # G4
|
|
major["V"] # G4
|
|
|
|
Keys and Chords
|
|
---------------
|
|
|
|
The :class:`~pytheory.scales.Key` class ties everything together —
|
|
scales, chords, and progressions:
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Key
|
|
|
|
key = Key("G", "major")
|
|
key.note_names # ['G', 'A', 'B', 'C', 'D', 'E', 'F#', 'G']
|
|
|
|
# All diatonic triads
|
|
key.chords
|
|
# ['G major', 'A minor', 'B minor', 'C major',
|
|
# 'D major', 'E minor', 'F# diminished']
|
|
|
|
# Build progressions from Roman numerals
|
|
chords = key.progression("I", "V", "vi", "IV")
|
|
[c.identify() for c in chords]
|
|
# ['G major', 'D major', 'E minor', 'C major']
|
|
|
|
# Detect the key from notes
|
|
Key.detect("C", "E", "G", "A", "D") # <Key C major>
|
|
|
|
Build chords directly:
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Chord
|
|
|
|
Chord.from_tones("C", "E", "G") # <Chord C major>
|
|
Chord.from_name("Am7") # <Chord A minor 7th>
|
|
Chord.from_intervals("G", 4, 7, 10) # <Chord G dominant 7th>
|
|
|
|
# Identify any chord
|
|
Chord.from_tones("Bb", "D", "F").identify() # 'Bb major'
|
|
|
|
# Analyze in a key
|
|
Chord.from_name("G7").analyze("C") # 'V7'
|
|
|
|
Guitar Fingerings
|
|
-----------------
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Fretboard, CHARTS
|
|
|
|
fb = Fretboard.guitar()
|
|
|
|
# Get a labeled fingering from the chord chart
|
|
f = CHARTS["western"]["C"].fingering(fretboard=fb)
|
|
f # Fingering(e=0, B=1, G=0, D=2, A=3, E=0)
|
|
f['A'] # 3
|
|
|
|
# Identify a chord from fret positions
|
|
fb.fingering(0, 0, 0, 2, 2, 0).identify() # 'E minor'
|
|
|
|
# ASCII tablature
|
|
print(CHARTS["western"]["Am"].tab(fretboard=fb))
|
|
# Am
|
|
# E|--0--
|
|
# B|--1--
|
|
# G|--2--
|
|
# D|--2--
|
|
# A|--0--
|
|
# E|--0--
|
|
|
|
Audio Playback
|
|
--------------
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Tone, Chord, play, save, Synth
|
|
|
|
# Play a tone
|
|
play(Tone.from_string("A4"), t=1_000)
|
|
|
|
# Play a chord with a different waveform
|
|
play(Chord.from_name("Am7"), synth=Synth.TRIANGLE, t=2_000)
|
|
|
|
# Save to a WAV file
|
|
save(Chord.from_name("C"), "c_major.wav", t=2_000)
|
|
|
|
Command Line
|
|
------------
|
|
|
|
PyTheory also works from the terminal::
|
|
|
|
$ pytheory tone A4
|
|
$ pytheory chord C E G
|
|
$ pytheory key G major
|
|
$ pytheory scale C dorian
|
|
$ pytheory fingering Am
|
|
$ pytheory progression C major I V vi IV
|
|
$ pytheory detect C E G A D
|
|
$ pytheory play Am7 --synth triangle
|
|
|
|
What's Included
|
|
---------------
|
|
|
|
- **6 musical systems**: Western, Indian (Hindustani), Arabic (Maqam),
|
|
Japanese, Blues/Pentatonic, Javanese Gamelan
|
|
- **40+ scales**: major, minor, harmonic minor, 7 modes, 10 thaats,
|
|
10 maqamat, 6 Japanese pentatonic scales, blues, pentatonic,
|
|
slendro, pelog, and more
|
|
- **Pitch calculation** in equal, Pythagorean, and meantone temperaments
|
|
- **Chord identification**: name any chord from its notes, intervals, or
|
|
MIDI numbers (17 chord types recognized)
|
|
- **Chord charts** with 144 pre-built chords (12 roots x 12 qualities)
|
|
- **Chord analysis**: consonance scoring, Plomp-Levelt dissonance,
|
|
beat frequency calculation, harmonic tension, voice leading
|
|
- **Key detection** and **Roman numeral analysis** (I-IV-V-I progressions)
|
|
- **Fingering generation** for 25 instruments with labeled string names,
|
|
including guitar (8 tunings), bass, ukulele, mandolin, and more
|
|
- **Audio playback** with sine, sawtooth, and triangle wave synthesis
|
|
- **WAV export** for saving rendered audio to disk
|