PyTheory: Music Theory for Humans

PyTheory is a Python library for exploring music theory, composing multi-part arrangements, and exporting them to MIDI, sheet music, or audio — with nothing to install but Python packages. No DAW, no samples, no plugins.

New to uv? It’s the fast Python package manager — one command to install, no virtualenv ceremony.

$ uv add pytheory

Why would I want this?

Different people come to PyTheory for different reasons. You might be:

  • Learning theory — you want to see what’s inside a chord, why a progression works, or what makes Dorian sound different from minor. PyTheory answers in code you can poke at. Start with Quickstart, then Music Theory Fundamentals.

  • Playing guitar — you want chord fingerings, scale diagrams, Nashville number charts, or tablature without opening a browser full of ads. Start with Instruments and Fingerings.

  • Sketching songs — you want to hear an idea now: four chords, a drum groove, a bass line, through your speakers in a dozen lines of Python. Export MIDI when it’s good and finish in your DAW. Start with Sequencing.

  • Playing live — you have a MIDI keyboard and want a synth rig in the terminal, with recording. Start with Live Performance.

  • Capturing ideas — you hummed a melody into your phone and want it as notes, MIDI, or sheet music. Score.from_wav("hum.m4a") transcribes it — or run pytheory studio and just drop the file in your browser. See Playback and Export.

  • Composing with AI — Claude Code can drive PyTheory from natural language: “write me a bossa nova in G minor” becomes a Score you can hear, edit, and export.

Theory

The theory layer works everywhere Python runs — no audio setup needed. Tones, scales, chords, keys, intervals, harmony, 16 musical systems:

>>> 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']

>>> Tone.from_string("C4").interval_to(Tone.from_string("G4"))
'perfect 5th'

Guitar

Chord fingerings, identification, scale diagrams, and tablature — for guitar and 24 other stringed instruments, in any tuning:

>>> from pytheory import Fretboard, Chord

>>> print(Fretboard.guitar().tab("Am"))
A minor
E|--x--
A|--0--
D|--2--
G|--2--
B|--1--
e|--0--

>>> Chord.from_symbol("F#m7b5").identify()
'F# half-diminished 7th'

>>> Fretboard.guitar().chord("G")
Fingering(E=3, A=2, D=0, G=0, B=0, e=3)

Melodies render to ASCII tablature too — write a line, print the tab, hand it to a guitarist. See Instruments and Fingerings for fingerings and scale diagrams, and Nashville Numbers, Blues Scales, and Tablature for Nashville number charts, blues scales, and full-song tabs.

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)

Everything you hear is synthesized from math — 56 waveforms, 83 instrument presets, 100 drum patterns, and a full effects rack (reverb, delay, chorus, distortion, sidechain, automation). When it sounds right, take it anywhere: WAV, MIDI, ABC notation, MusicXML, LilyPond, or guitar tab.

Or hear a randomly generated track from the command line — different every time:

$ uv run pytheory demo

Start Here

Making Music

Guitar & Strings

Theory Reference

Tools

API Reference

Project

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