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:

>>> 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:

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)

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

User Guide

API Reference

Project

Music is math that makes you feel something. PyTheory gives you the math. What you feel is up to you.