mirror of
https://github.com/kennethreitz/pytheory.git
synced 2026-06-05 06:46:14 +00:00
kennethreitz
c1925af69d
New documentation section covering the Nashville number system, blues scale theory, and tablature export — topics that were previously scattered across cookbook and fretboard docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
151 lines
4.7 KiB
ReStructuredText
151 lines
4.7 KiB
ReStructuredText
PyTheory: Music Theory for Humans
|
|
=================================
|
|
|
|
**PyTheory** is a Python library for exploring music theory, composing
|
|
multi-part arrangements, and exporting them to MIDI for your DAW.
|
|
|
|
Use it to learn theory by doing — build chords from intervals and hear
|
|
the result. Use it to sketch song ideas faster than clicking through a
|
|
DAW. Use it with Claude Code to prototype
|
|
music from natural language. Or just use it to answer "what chords are
|
|
in G major?" without opening a browser.
|
|
|
|
::
|
|
|
|
$ pip install pytheory
|
|
|
|
Theory
|
|
------
|
|
|
|
The theory layer works everywhere Python runs — no audio setup needed.
|
|
Tones, scales, chords, keys, intervals, harmony, 16 musical systems,
|
|
60+ instruments:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> from pytheory import Key, Chord, Tone
|
|
|
|
>>> Key("C", "major").chords
|
|
['C major', 'D minor', 'E minor', 'F major', 'G major', 'A minor', 'B diminished']
|
|
|
|
>>> [c.symbol for c in Key("G", "major").progression("I", "V", "vi", "IV")]
|
|
['G', 'D', 'Em', 'C']
|
|
|
|
>>> Chord.from_symbol("F#m7b5").identify()
|
|
'F# half-diminished 7th'
|
|
|
|
>>> Tone.from_string("C4").interval_to(Tone.from_string("G4"))
|
|
'perfect 5th'
|
|
|
|
Composition
|
|
-----------
|
|
|
|
When you're ready to make noise, the composition layer adds drums,
|
|
synths, effects, and multi-part arrangements. Sketch an idea, hear
|
|
it through your speakers, export MIDI, finish in your DAW:
|
|
|
|
.. code-block:: python
|
|
|
|
from pytheory import Score, Key, Duration
|
|
from pytheory.play import play_score
|
|
|
|
score = Score("4/4", bpm=120)
|
|
score.drums("rock", repeats=8, fill="rock", fill_every=4)
|
|
|
|
piano = score.part("piano", instrument="piano", reverb=0.3)
|
|
lead = score.part("lead", synth="saw", envelope="pluck",
|
|
delay=0.2, reverb=0.2, lowpass=4000)
|
|
bass = score.part("bass", synth="triangle", lowpass=900)
|
|
|
|
for chord in Key("G", "major").progression("I", "V", "vi", "IV") * 2:
|
|
piano.add(chord, Duration.WHOLE)
|
|
|
|
lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5)
|
|
lead.add("G5", 1).add("E5", 1)
|
|
lead.add("D5", 0.5).add("B4", 0.5).add("A4", 1)
|
|
lead.add("G4", 2).rest(2)
|
|
|
|
for n in ["G2", "G2", "D2", "D2", "E2", "E2", "C2", "C2"] * 2:
|
|
bass.add(n, Duration.HALF)
|
|
|
|
play_score(score)
|
|
|
|
.. raw:: html
|
|
|
|
<audio controls style="width:100%;margin:0.5em 0 1.5em"><source src="_static/audio/quickstart.wav" type="audio/wav"></audio>
|
|
|
|
Or hear a randomly generated track from the command line — different
|
|
every time::
|
|
|
|
$ pytheory demo
|
|
|
|
What's Inside
|
|
-------------
|
|
|
|
- **Theory** — tones, scales (40+ across 16 systems), chords (17 types),
|
|
keys, Roman numeral analysis, figured bass, pitch class sets (Forte
|
|
numbers), scale recommendation, modulation, voice leading, enharmonic
|
|
support (Cb, Fb, E#, B#, double sharps/flats, unicode symbols)
|
|
- **Sequencing** — Score, Parts, arpeggiator, legato/glide, velocity,
|
|
swing, humanize, tempo changes, song sections with repeat, strumming,
|
|
pitch bends (3 types), rolls, tuning systems (TET factory, 4
|
|
temperaments, reference_pitch)
|
|
- **Synthesis** — 41 waveforms (including Karplus-Strong pluck, Hammond organ,
|
|
bowed string, granular, vocal/formant, and 31 dedicated instrument synths),
|
|
10 envelopes, 60+ instrument presets, configurable FM, sub-oscillator,
|
|
noise layer, filter envelope, velocity-to-brightness, analog oscillator
|
|
drift, detune, stereo pan/spread, 80+ drum patterns (stereo panned,
|
|
including world percussion and cajón), 21 fills, 11 microtonal systems
|
|
- **Effects** — reverb (algorithmic + 7 convolution IRs, stereo), delay,
|
|
lowpass/highpass (with resonance), distortion, guitar cabinet simulation,
|
|
saturation, chorus, phaser, tremolo, analog drift, sidechain compression,
|
|
automation, LFOs. Master bus compressor/limiter
|
|
- **Instruments** — 60+ presets with fingering generation, guitar strumming,
|
|
pitch bends, note choking
|
|
- **Output** — stereo playback, WAV export, MIDI import/export
|
|
- **Interface** — REPL with tab completion, CLI (15 commands), ``pytheory demo``,
|
|
KeyboardInterrupt handling for clean stop
|
|
- **AI-friendly** — Claude Code can compose
|
|
and play music through PyTheory from natural language
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:caption: User Guide
|
|
|
|
guide/quickstart
|
|
guide/theory
|
|
guide/tones
|
|
guide/scales
|
|
guide/chords
|
|
guide/fretboard
|
|
guide/nashville-blues-tabs
|
|
guide/systems
|
|
guide/sequencing
|
|
guide/synths
|
|
guide/effects
|
|
guide/drums
|
|
guide/playback
|
|
guide/repl
|
|
guide/cli
|
|
guide/cookbook
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:caption: API Reference
|
|
|
|
api/tones
|
|
api/scales
|
|
api/chords
|
|
api/charts
|
|
api/play
|
|
api/systems
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
:caption: Project
|
|
|
|
changelog.md
|
|
|
|
Music is math that makes you feel something. PyTheory gives you the
|
|
math. What you feel is up to you.
|