songtools

A Python DSL for composing music from code. Notes carry expression, structure carries time. No magic strings, no duplicate logic or state.

Install

uv add songtools

Requires Python 3.14+ and sounddevice (PortAudio backend).

Core idea

The library revolves around the Sound object. Use the @ operator to transform sounds:

• sound @ Effect: Applies a DSP effect.
• sound @ Key: Applies a harmonic context.
• sound @ Degree: Applies a relative pitch shift based on a key.

Abstractions

Operators

Vocabulary

• Notes/Degrees: Degree.I through Degree.VII.
• Scales: Scale.MAJOR, Scale.MINOR, Scale.DORIAN.
• Qualities: Quality.TRIAD, Quality.SEVENTH, Quality.NINTH, Quality.SUS2, Quality.SUS4, Quality.POWER.
• Roots: KeyRoot.C, KeyRoot.CS, etc.

Effects

Chain effects on any Sound using @:

Quick start

from datetime import timedelta
from songtools.lib import (
    Sound, Key, KeyRoot, Scale, Quality,
    Degree, Decay, LowPass, WavFile
)

# Create a simple tone
tone = Sound.tone(440.0, 44100)

# Apply transformations and effects
# A C-Major chord sequence with a lowpass filter
melody = (tone @ Key(KeyRoot.C, Scale.MAJOR, Quality.TRIAD) @ Degree.I) @ LowPass(2000)

# Sequence notes
song = Sound.sequence(melody @ Decay(timedelta(seconds=0.5)), tone @ Decay(timedelta(seconds=0.2)), bpm=bpm)

# Play or Save
song.play()
WavFile("output.wav").write(song)

License

MIT