PyTheory is music theory for humans — a Python library that models tones, scales, chords, keys, fretboards, and rhythm in a way people can actually read. It speaks twelve-tone Western harmony fluently, but it isn't limited to it: Indian rāgas, Arabic maqāmāt, gamelan slendro & pelog, 19-TET, and a dozen other tonal systems are first-class citizens, complete with microtonal synthesis.
This playground
Everything on this site is computed live by pytheory on the server — no music theory is re-implemented in JavaScript. Each card cites the API call behind it. Explore:
- Guitar Tab — chord charts for six fretted instruments, with custom tunings, capo, and a click-to-edit fretboard that names whatever you finger.
- Chord Lab — voicings, inversions, tension, pitch-class set theory, and tritone substitutions for any chord symbol.
- Scales — every scale and mode across sixteen tonal systems, harmonized and playable.
- Keys & Progressions — diatonic chords, borrowed chords, secondary dominants, named progressions, and a modulation planner.
- Tools — identify chords from fret positions, analyze progressions, detect keys, transcribe hummed or whistled recordings into notation, and convert MIDI to LilyPond (with PDF engraving), ABC, MusicXML, or tab.
Install it
Not familiar with uv? It's the fast Python package manager — install it here.
$ uv add pytheory
Then, in a REPL:
>>> from pytheory import Fretboard, CHARTS >>> print(CHARTS["western"]["Cmaj7"].tab(fretboard=Fretboard.guitar()))
Links
—
Click the diagram to build your own voicing — above the nut toggles open / muted. Matching chords get selected automatically.
More voicings NamedChord.fingerings(…)
ASCII tab NamedChord.tab(fretboard=…)
On the neck TonedScale / Chord + fretboard, same tuning & capo
Root notes in red. Click any note to hear it. Follows the instrument, tuning, and capo above.
Tuner pytheory.tuner.Tuner · analyze_frame(…)
Tap the stream from your own JS — three lines
const tuner = new EventSource("http://localhost:8123/stream");
tuner.onmessage = (e) => {
const { freq, note, octave, cents, in_tune } = JSON.parse(e.data);
};
Open strings click to hear a reference tone
Allow microphone access, play one string at a time, and tune until the needle centers. Strings light up as you get close.
—
| intervals | |
| pitch classes | |
| Forte number | |
| figured bass | |
| tension | |
| dissonance |
Voicings chord.inversion() · .drop2() · .open_voicing()
Substitutions chord.tritone_sub() · .extensions()
Tuning & beats chord.beat_frequencies · Score(temperament=…)
The same chord in four temperaments — equal splits the octave evenly, just locks to pure ratios; listen for the beating.
Beat frequencies
Voice leading chord.voice_leading(other)
Solo over it scale.recommend(…)
Scales that fit this chord's tones — improv starting points.
—
Harmonized scale.harmonize()
On the fretboard fretboard.scale_diagram(scale)
Circle of fifths Key(…).signature · key.relative
Click a key to explore it.
—
Progression key.progression(…)
Beyond the key key.borrowed_chords · key.secondary_dominant(…)
Borrowed (modal interchange)
Secondary dominants
What next? key.suggest_next(…)
Modulation planner key.modulation_path(…) · key.pivot_chords(…)
Groove Lab score.drums(preset, fill=…) · Score(swing=…)
One hundred drum patterns from pytheory's rhythm engine — bossa nova to blast beat, dhol chaal to drum and bass — with auto-fills, swing, and an optional chord backing cycled underneath. Rendered to audio server-side, exportable as MIDI.
Hum it → harmonize it Score.from_wav · Key.detect · scale.harmonize()
Hum or whistle a melody. pytheory transcribes it, detects the key, picks a chord for every bar, and plays your tune back with piano and bass — printable as sheet music.
Note inspector Tone.solfege · .helmholtz · .overtones(…)
Overtone series why the 7th harmonic sounds "off"
Chord identifier Fingering.identify()
Progression analyzer analyze_progression(…)
Key detector Key.detect(…)
Audio → LilyPond / ABC / Tab Score.from_wav(…)
Hum a melody, whistle a hook, or record a bass line — monophonic transcription via YIN pitch tracking. WAV, m4a voice memos, and mp3 all work.
MIDI → LilyPond / ABC / Tab Score.from_midi(…)
No MIDI handy? Grab one from the Keys & Progressions tab with the MIDI button.