PyCodeDJ Manual

Write Python code. Hear it change in real time.

1. What PyCodeDJ Does

PyCodeDJ turns Python source code into live music. It parses files, reads @loop blocks, maps code structure to musical parameters, and sends OSC messages to SuperCollider.

from pycodedj import dj, loop

@loop(interval=2.0)
def bass():
    dj.volume = 0.4
    for i in range(8):
        if i % 2 == 0:
            pass

@loop(synth="kick_floor", beat=0.25)
def kick():
    dj.volume = 0.8
    dj.pattern = "x . x ."

The function name is the loop name. Use it with pycodedj eval demo.py::bass, mute, and stop.

2. Install and Start

pip install 'pycodedj[watch]'

Open sc/synths.scd in SuperCollider, run it, and confirm:

PyCodeDJ synths loaded. Ready. OSC port: 57120

pycodedj eval examples/demo.py::bass

3. Basic Loop Syntax

from pycodedj import dj, loop

@loop(interval=1.0)
def loop_name():
    dj.volume = 0.3
    dj.eq = "flat"
    pass

Setting	Meaning	Default
`dj.volume`	Amplitude, 0.0 to 1.0	`0.3`
`dj.eq`	EQ preset	`"flat"`
`dj.low/mid/high`	Per-band EQ override, 0.0 to 2.0	preset value
`dj.pattern`	Rhythm and pitch pattern	none

@loop(interval=0.25)
def hats():
    dj.volume = 0.08
    dj.eq = "edm"
    dj.low = 0.5
    dj.high = 1.25

Preset	Character
`"flat"`	No adjustment
`"classic"` / `"classical"`	Restrained lows/highs, forward mids
`"jazz"`	Warm lows, forward mids, soft highs
`"rock"` / `"pop"`	Slight low and high boost
`"edm"` / `"hiphop"`	Stronger low end
`"acoustic"`	Restrained lows, slight mid-high lift

4. Code Structure Mapping

When dj.pattern is absent, the shape of the function body controls sound.

Code feature	Music parameter	Effect
Max block depth	Filter cutoff	Deeper code sounds brighter
`if` / `for` / `while` count	LFO rate	More control flow moves faster
Nested `def` count	Voice count	More functions add voices
Comment ratio	Reverb mix	More comments add space

5. Rhythm and Pitch with dj.pattern

@loop(synth="bass_acid", root="A1", scale="minor", beat=0.25)
def bass():
    dj.volume = 0.35
    dj.pattern = "0 . [0 3] ~ 5 . 3 ."

Token	Meaning
`x`	Trigger at root note
`.`	Rest
`0`, `1`, ...	Scale degree
`[0 3]`	Chord
`~`	Tie

dj.pattern = p1 is intentionally not supported. Keep pattern strings visible in the loop body.

6. Multiple Loops

@loop(synth="kick_floor", beat=0.25)
def kick():
    dj.volume = 0.8
    dj.pattern = "x . x ."

@loop(interval=4.0)
def pad():
    dj.volume = 0.08
    # wide space
    pass

pycodedj watch examples/demo.py

7. Sound Reference

Use synth= to choose a SuperCollider synth. The function name remains the loop name; synth= only chooses the sound.

@loop(synth="bass_acid", root="A1", scale="minor", beat=0.25)
def acid():
    dj.volume = 0.25
    dj.pattern = "0 . 3 . 5 ."

Audition all sounds one at a time:

pycodedj eval examples/sound_showcase.py::kick_floor
pycodedj eval examples/sound_showcase.py::bass_acid
pycodedj eval examples/sound_showcase.py::lead_acid

Kicks

Synth	Character	Good for
`kick_hard`	Tight, punchy, short attack	Strong downbeats and minimal patterns
`kick_floor`	Full four-on-the-floor club kick	Main kick in dance/techno loops
`kick_pulse`	Lighter pulse kick	Secondary pulse, softer rhythmic support
`kick_soft`	Rounder kick with less click	Warm grooves and quieter sections
`kick_909`	Long electronic kick tail	House and techno foundations
`kick_click`	Short kick with a clear transient	Fast patterns that need definition

Bass

Synth	Character	Good for
`bass_rumble`	Deep, loose low-end pressure	Rumble layers under a kick
`bass_reese`	Wide, moving Reese-style bass	Dark basslines and sustained movement
`bass_sub`	Clean sine-like sub weight	Fundamental low notes and floor pressure
`bass_acid`	Resonant 303-like acid tone	Patterned basslines and squelchy sequences
`bass_pluck`	Short plucked bass	Syncopated low-end hooks
`bass_fm`	Metallic FM low tone	Percussive basslines
`bass_mono`	Simple mono synth bass	Stable bass phrases
`bass_wobble`	Filter-modulated bass	Dubstep-style movement and breakdowns

Percussion

Synth	Character	Good for
`hat_engine`	Short closed/open hat texture	16th-note grids and forward motion
`hat_ride`	Longer open hat / ride color	Offbeats and sustained top-end energy
`clap_snap`	Sharp, dry clap	Snappy accents
`clap_snare`	Broader snare-like clap	Backbeats on beats 2 and 4
`tom_drum`	Pitch-swept tom	Fills, transitions, low percussion
`snare_roll`	Repeated snare texture	Rolls and build-ups
`crash_noise`	Long noisy crash	Section changes and impacts
`rim_shot`	Dry rim transient	Sparse syncopation
`cowbell`	Metallic two-tone hit	Classic machine percussion
`perc_blip`	Small pitched blip	Minimal percussion and call-response details
`shaker_loop`	Continuous shaker texture	Top-end groove and motion
`tick_metal`	Tiny metallic tick	Glitch grids and high-frequency accents
`wood_block`	Woody resonant knock	Dry percussion patterns

Chords and Stabs

Synth	Character	Good for
`chord_rave`	Bright rave stab	Short chord hits and hooks
`stab_neon`	Glossy synthetic stab	Melodic accents
`chord_dub`	Soft dub-techno chord	Spacious chord pulses
`stab_saw`	Detuned saw stab	Aggressive harmonic accents
`chord_organ`	Organ-like sustained chord	Warm harmonic beds
`bell_rave`	Metallic FM bell	Bright melodic stabs
`pad_minor`	Dark minor pad	Suspense and darker harmonic beds
`chord_deep`	Low filtered chord	Deep house / dub-techno pulses
`chord_glass`	Clear glassy chord	Clean bright harmonic accents
`pad_warm`	Smooth analog-style pad	Soft background harmony
`pad_string`	Bowed string-like synth pad	Long sustained emotional layers
`pad_choir`	Vocal-formant pad	Choral beds without a lead vocal

Leads and Notes

Synth	Character	Good for
`lead_acid`	Acid-style lead	Melodic sequences
`lead_hoover`	Hoover-like lead	Big sustained gestures
`pluck_soft`	Gentle plucked tone	Sparse melodies
`arp_synth`	Arpeggiated synth tone	Fast melodic motion
`lead_square`	Hollow square-wave lead	Retro melodic hooks
`lead_fm`	Bell-like FM lead	Bright digital melodies
`lead_chip`	Short chiptune lead	Fast arcade-like phrases
`lead_saw`	Detuned saw lead	Larger melodic lines
`lead_whistle`	Thin sine-like whistle	High counter-melodies
`note`	Neutral note synth	General `dj.pattern` pitch tests and chords

Atmosphere and FX

Synth	Character	Good for
`pad_shimmer`	Wide, slow shimmer	Background pads
`air_warehouse`	Industrial room tone	Space, air, and noise bed
`vox_ahh`	Vocal-like formant pad	Breath and choir-like layers
`fx_drop`	Low impact hit	Drops and transitions
`fx_riser`	Rising noise sweep	Build-ups
`fx_glitch`	Small glitch clicks	Detailed percussive texture
`drone_space`	Low evolving drone	Long ambient beds
`fx_down`	Descending noise sweep	Drops and section endings
`fx_zap`	Short falling laser-like hit	Small FX punctuation
`fx_noise`	Filtered noise burst	Impacts and transitions
`fx_laser`	Pitch-bending laser FX	Sci-fi accents
`fx_vinyl`	Crackle and hiss bed	Texture and lo-fi background

8. CLI Reference

pycodedj eval FILE::LOOP
pycodedj watch examples/demo.py
pycodedj panic
pycodedj stop bass
pycodedj mute bass
pycodedj unmute bass

9. Troubleshooting

No sound: boot SuperCollider, run sc/synths.scd, confirm the OSC port, then run pycodedj eval examples/demo.py::bass.

Loop not found: the name after :: must match the Python function name.

10. Under the Hood

PyCodeDJ parses Python with ast. loop, dj, and pattern are runtime helpers so files can still be imported normally.