Live Performance¶

Everything else in PyTheory renders music ahead of time: you describe a Score, it computes the audio, you hear the result. Live mode is the opposite — you play, and PyTheory is the instrument. Plug in a MIDI keyboard (or just use your computer keyboard), assign synths to channels, and notes sound as you press keys.

Why would you want this? Because the fastest way to find a melody is to play one. Sketching in code is great for arrangement and structure, but noodling on keys is how you discover the part worth writing down. Live mode closes that loop: improvise until something clicks, record it, export it as MIDI or a Score, and keep composing in code.

Live MIDI needs one extra dependency:

$ pip install "pytheory[live]"

(That installs python-rtmidi. Keyboard-only mode works without it.)

The Live Engine¶

LiveEngine maps MIDI channels to PyTheory instruments and synthesizes audio in real time:

from pytheory.live import LiveEngine

engine = LiveEngine()
engine.channel(1, instrument="electric_piano")
engine.channel(2, instrument="bass_guitar")
engine.channel(10, drums=True)        # channel 10 = drums, per MIDI convention
engine.start()                        # blocks until Ctrl-C

Each channel takes the same parameters as Score.part() — any instrument preset, synth waveform, envelope, or effect:

engine.channel(1, synth="saw", envelope="pluck", lowpass=4000, reverb=0.3)
engine.channel(2, instrument="rhodes", chorus=0.4)

Behind the scenes the engine pre-renders each note’s waveform into a cache when it starts, so the audio callback only has to mix — that’s what keeps latency low enough to play. Sustaining instruments (organs, pads, strings) loop seamlessly inside their wavetables, so a held key rings for as long as you hold it; percussive instruments (pianos, plucks, mallets) decay naturally, just like the real thing.

Effects run on each channel’s bus in real time — reverb tails, filter sweeps, and delay feedback are computed per audio block, not baked into the notes.

No MIDI Hardware? Use Your Keyboard¶

The engine can treat your computer keyboard as a two-octave piano — bottom letter rows are the lower octave, number rows the upper, laid out like piano keys (Z X C V B N M are the white keys, S D G H J the black keys):

engine.keyboard_play(ch=1)
engine.start()

Map Hardware Knobs to Parameters¶

Map any MIDI CC (a knob or slider on your controller) to any channel parameter — filter sweeps, volume, reverb sends, distortion — and turn the knob while you play:

engine.cc(11, "lowpass", min_val=200, max_val=8000)
engine.cc(12, "volume", min_val=0.0, max_val=1.0)
engine.cc(13, "reverb", min_val=0.0, max_val=0.8)

Knob turns apply on the very next audio block (~3ms at the default buffer size) — sweep the filter mid-phrase and it responds like a hardware synth.

Drums Synced to MIDI Clock¶

If your controller or groovebox sends MIDI clock (an OP-XY, a Digitakt, most hardware sequencers), the engine can run a drum pattern locked to its transport — start, stop, and tempo all follow the hardware:

engine.drums("house", volume=0.5)
engine.start()

Any of the 100 Pattern presets works — see Drums.

Record What You Play¶

The whole point of improvising is keeping the good take. The engine records incoming MIDI and exports it as a file or a Score:

engine.start_recording()
# ... play ...
engine.stop_recording()

engine.export_recording("take1.mid")        # save as MIDI
score = engine.export_recording(filename=None)   # or get a Score back

A recording that comes back as a Score drops you into the rest of PyTheory — change the synths, add effects, layer more parts, export to sheet music. Improvise first, arrange after.

The Live TUI¶

For a ready-made performance setup, the live TUI builds an 8-channel rig with randomly chosen instruments, a drum pattern, and a terminal dashboard showing what’s playing:

$ pytheory live

Every run picks a different instrument combination (the seed is printed so you can resume a setup you liked). Inside the TUI you can swap instruments per channel, change the drum pattern, record, and export — without leaving the keyboard.

Saving a Rig¶

Engine configurations serialize to JSON, so a setup you like is one line to save and one to restore:

engine.save_config("my_rig.json")

engine = LiveEngine()
engine.load_config("my_rig.json")
engine.start()

The Tuner¶

Every musician needs a tuner, and you already have a microphone. PyTheory’s tuner tracks your pitch live (same YIN algorithm as the transcriber) and shows the note plus how many cents sharp or flat you are:

$ pytheory tune
  A4  ----------------------------●------ +12.3¢ ( 443.14 Hz)

For a big, friendly needle, serve it to your browser instead:

$ pytheory tune --serve

That opens http://localhost:8123 — note name, frequency, and a needle that turns green within ±5 cents.

The page is fed by a Server-Sent Events stream at /stream, with CORS open — which means any JavaScript app can tap PyTheory’s pitch detection directly, no client library required:

const tuner = new EventSource("http://localhost:8123/stream");
tuner.onmessage = (e) => {
    const reading = JSON.parse(e.data);
    if (reading) {
        // { freq: 440.0, note: "A", octave: 4,
        //   cents: -3.2, in_tune: true }
        updateMyUI(reading);
    }
};

Build your own tuner page, drive a game, pitch-train an ear-training app — the stream doesn’t care what’s listening.

Orchestras tuning high? pytheory tune --ref 442. Python access is pytheory.tuner.Tuner (tuner.reading holds the latest analysis) and pytheory.tuner.analyze_frame() for one-shot use.