pytheory

PyTheory: music theory for humans

Explore music theory, compose multi-part arrangements, and hear them instantly — all in Python.

▶ Try it in your browser — a live demo of what PyTheory can do, nothing to install.
Documentation · PyPI · Changelog · Claude Skill

$ pip install pytheory
$ pytheory demo        # hear a generated track right now

Sketch Ideas Fast

from pytheory import Score, Chord, Duration
from pytheory.play import play_score

score = Score("4/4", bpm=140)
score.drums("bossa nova", repeats=4)

chords = score.part("chords", synth="fm", envelope="pad", reverb=0.4)
lead = score.part("lead", synth="saw", envelope="pluck", delay=0.3, lowpass=3000)
bass = score.part("bass", synth="sine", lowpass=500)

for sym in ["Am", "Dm", "E7", "Am"]:
    chords.add(Chord.from_symbol(sym), Duration.WHOLE)
    chords.add(Chord.from_symbol(sym), Duration.WHOLE)

lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)
lead.arpeggio("Dm", bars=2, pattern="updown", octaves=2)
lead.set(lowpass=5000, reverb=0.4)
lead.arpeggio("E7", bars=2, pattern="up", octaves=2)
lead.arpeggio("Am", bars=2, pattern="updown", octaves=2)

for n in ["A2", "E2", "A2", "C3"] * 4:
    bass.add(n, Duration.QUARTER)

play_score(score)              # hear it now
score.save_midi("sketch.mid")  # open in your DAW

Music Theory

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

>>> Key("C", "major").pivot_chords(Key("G", "major"))
['A minor', 'B minor', 'C major', 'D major', 'E minor', 'G major']

>>> from pytheory.scales import Scale
>>> Scale.recommend("C", "Eb", "F", "Gb", "G", "Bb", top=3)
[('C', 'blues', 1.0), ...]

Guitar

Chord fingerings, tabs, and scale diagrams for guitar and 24 other stringed instruments:

>>> from pytheory import Fretboard

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

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

Melodies and basslines render to ASCII tablature with part.to_tab(), and chord charts work in Nashville numbers too.

Composition

Song structure with sections, repeats, and parameter automation:

score = Score("4/4", bpm=124)
score.drums("house", repeats=16, fill="house", fill_every=8)

pad = score.part("pad", synth="supersaw", envelope="pad",
                 reverb=0.5, chorus=0.3, sidechain=0.85)
lead = score.part("lead", synth="saw", envelope="pluck",
                  legato=True, glide=0.03, humanize=0.3)
bass = score.part("bass", synth="sine", lowpass=300, sidechain=0.7)

score.section("verse")
# ... add notes ...
score.section("chorus")
lead.set(lowpass=5000, reverb=0.3)
# ... add notes ...
score.end_section()

score.repeat("verse")
score.repeat("chorus", times=2)

Batteries Included

56 synth waveforms — the 10 classics (sine, saw, triangle, square, pulse, FM, noise, supersaw, PWM) plus 46 modeled instruments: Rhodes, Wurlitzer, pipe organ, vibraphone, choir, sitar, theremin, and more.
100 drum patterns — rock, jazz, bebop, bossa nova, salsa, samba, afrobeat, funk, reggae, house, trap, metal, drum and bass, and 87 more. 37 fill presets, 74 synthesized percussion sounds, stereo panned like a real kit.
6 effects with automation — distortion, chorus, lowpass, delay, reverb, and LFO modulation on any parameter. Sidechain compression, master bus compressor/limiter, stereo output.
Convolution reverb — 7 impulse responses: Taj Mahal (12s), cathedral, plate, spring, cave, parking garage, canyon.
6 musical systems — Western, Indian (Hindustani), Arabic (Maqam), Japanese, Blues/Pentatonic, Javanese Gamelan. 40+ scales.
83 instrument presets — guitar (8 tunings), bass, ukulele, mandolin family, violin family, banjo, harp, oud, sitar, erhu, and more.

lead = score.part("lead", synth="saw",
                  distortion=0.7, lowpass=1000, lowpass_q=5.0,
                  delay=0.3, reverb=0.4, reverb_type="plate")

lead.set(lowpass=4000, distortion=0.9)                  # automate mid-song
lead.lfo("lowpass", rate=0.5, min=400, max=3000, bars=8)  # LFO modulation

Command Line

$ pytheory repl                            # interactive scratchpad
$ pytheory demo                            # hear a generated track
$ pytheory key G major                     # explore a key
$ pytheory identify Cmaj7                  # analyze a chord symbol
$ pytheory progression C major I V vi IV   # build a progression
$ pytheory midi C major I V vi IV -o out.mid
$ pytheory play Am7 --synth saw --envelope pluck
$ pytheory modes C                         # show all modes
$ pytheory circle C                        # circle of fifths
$ pytheory tune --instrument guitar        # strobe tuner, string-locked
$ pytheory studio                          # browser: recording → sheet music
$ pytheory live --link                     # MIDI synth rig, Ableton Link sync

Live MIDI input and Ableton Link sync are optional extras:

$ pip install "pytheory[live]"   # MIDI input (python-rtmidi)
$ pip install "pytheory[link]"   # Ableton Link sync

Why Python?

A DAW is great for tweaking sounds. But when you're thinking about music — code is faster than clicking. Sketch ideas, hear them instantly, export MIDI, finish in your DAW.

Tools like Claude Code can use PyTheory to prototype musical ideas from natural language — "write a bossa nova in A minor with a saw lead and reverb" becomes real, playable music.

Talk to it with Claude

PyTheory ships an official Claude Code plugin — six skills that let Claude compose, analyze, and notate music for you. In Claude Code:

/plugin marketplace add kennethreitz/pytheory-skill
/plugin install composing-with-pytheory@pytheory

Then just ask — "write me a bossa nova in G minor", "what's the fingering for F#m7b5?", "turn this hum into a lead sheet". See the guide. For a real album made entirely in PyTheory, hear Interpretations.

Learn More

playground.pytheory.org — try PyTheory in your browser, nothing to install.
pytheory.org — guides, API reference, and audio examples.
pytheory-skill — the official Claude Code plugin (six skills) to make music by talking to Claude.
ableton-pytheory — drive Ableton Live from PyTheory, for those interested.

Metadata

Release files for pytheory 0.57.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytheory 0.57.13
File	Size	Uploaded
pytheory-0.57.13.tar.gz	368.3 kB	Jul 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pytheory 0.57.13
File	Interpreter	ABI	Platform	Reset
pytheory-0.57.13-py3-none-any.whl 298.5 kB Jul 7, 2026	Python 3	none	any	Details

Total release size: 666.8 kB

Release files / pytheory-0.57.13.tar.gz

Download URL	pytheory-0.57.13.tar.gz
Size	368.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`2ab86a5bff01818f79c8e0d48e63e2695e5fed225a308b97552334c0084d141f`
BLAKE2b-256 checksum How to use checksums	`f0842539e8bb9ff29e4c211a6502d06ac35087ffaf5cfc25ddddb8e3ca036e5f`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.6`

Release files / pytheory-0.57.13-py3-none-any.whl

Download URL	pytheory-0.57.13-py3-none-any.whl
Size	298.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c3ae028d0788a7bdf380d6d8344454bc959ec99c84bb3e8b99c3ac8490c7cf41`
BLAKE2b-256 checksum How to use checksums	`aed9fa29ed6e1d6e27b4197b37e00ec5515ac65f7f179e6974e5b9fdfb6ac3ac`
Upload date	Jul 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.6`