composing-with-pytheory

Composing with PyTheory

PyTheory turns music theory into runnable Python. You build a Score, add parts (chords, melodies, basslines) and drums, then render it to audio or MIDI — every sound is synthesized from math, so there are no samples, plugins, or DAW to install.

How to work

1. Write a short Python script that builds a Score and either plays it or saves it. Don't compose by chaining shell one-liners — a script is clearer, reproducible, and easy to iterate on.
2. Run it with uv run python song.py when uv is available, otherwise python3 song.py.
3. To let the user hear it, call play_score(score) (speakers) or render to a WAV they can open. To hand off to a DAW, save MIDI.

If PyTheory isn't installed, prefer uv when available: uv pip install pytheory (or uv add pytheory in a uv project); otherwise pip install pytheory. For live MIDI input add the extra: uv pip install "pytheory[live]" (or pip install "pytheory[live]"). NumPy/SciPy ship as PyTheory dependencies, so the scipy.io.wavfile WAV export below needs no extra install.

Core building blocks

from pytheory import Score, Key, Chord, Duration

score = Score("4/4", bpm=120)          # time signature + tempo

# A part is a voice with its own synth/instrument and effects.
piano = score.part("piano", instrument="piano", reverb=0.3)
lead  = score.part("lead", synth="saw", envelope="pluck", lowpass=4000)
bass  = score.part("bass", synth="triangle", lowpass=900)

# Chords from a Key's progression (Roman numerals) or Chord.from_symbol.
for chord in Key("G", "major").progression("I", "V", "vi", "IV"):
    piano.add(chord, Duration.WHOLE)

# Melodies are note names + durations (a float = beats, or Duration.*).
lead.add("D5", 1).add("B4", 0.5).add("D5", 0.5).add("G5", 2)
lead.rest(2)

for n in ["G2", "D2", "E2", "C2"]:
    bass.add(n, Duration.WHOLE)

• part.add(note_or_chord, duration) chains and returns the part. part.rest(duration) inserts silence.
• Duration.WHOLE / HALF / QUARTER / EIGHTH / SIXTEENTH plus dotted variants (DOTTED_HALF, DOTTED_QUARTER, …), or pass a float in beats (1, 0.5, 0.25, 0.125).
• Key(tonic, mode).progression("I", "V", "vi", "IV") returns Chords (lowercase numeral = minor, e.g. "i", "VI"). Key(...).chords lists the diatonic chords; Key(...).scale gives the scale tones. Chord.from_symbol("F#m7b5") parses any symbol.
• Note names are scientific pitch (C4 = middle C). Tone.from_string("A1") builds an explicit pitch; tone.add(12)/tone.add(-12) shift octaves.