PyCodeDJ

日本語版 README はこちら · Full Manual (EN) · マニュアル (JA)

A live-coding environment that translates Python code structure into music in real time. Every save changes the performance.

Concept

PyCodeDJ connects "writing code" directly to "making sound."

Add more for loops and the modulation speeds up. Deepen nesting and the filter opens up. Fill in comments and the space grows. Write dj.pattern = "x . x ." and that rhythm plays. Write dj.pattern = "0 . 3 . 5 ." and those pitches ring out.

Two things set it apart from existing Python ↔ SuperCollider bridges (sc3nb, supriya):

• Hot-reload performance — swap out a loop without stopping it. Saving a file is an immediate sound change.
• Two performance styles — auto-generation from code structure, and explicit dj.pattern notation for rhythm and pitch. Mix them freely in the same file.

Architecture

[Python engine]  →OSC→  [SuperCollider]  →audio out→  speakers
      ↓ OSC
  [Hydra etc.]  →video out→  screen

BPM clock is held by SuperCollider's TempoClock. Python only sends parameter updates over OSC; timing accuracy is delegated to SuperCollider.

Code Structure → Music Parameter Mapping

Installation

Requirements

• Python 3.10 or later
• SuperCollider (with scsynth available)

pip install 'pycodedj[watch]'

The [watch] extra enables the pycodedj watch command.

Development install:

git clone https://github.com/kanekoyuichi/pycodedj
cd pycodedj
pip install -e ".[dev]"

Quick Start

1. Boot SuperCollider and load the synths

Open sc/synths.scd in the SuperCollider IDE. Press Ctrl+A (Cmd+A on Mac) to select all, then Ctrl+Enter (Cmd+Enter on Mac) to run. When the Post window shows this, you're ready:

PyCodeDJ synths loaded. Ready. OSC port: 57120

2. Write a live-coding file

from pycodedj import dj, loop

# Code-structure mode: the shape of your code maps to sound
@loop(interval=2.0)
def bass():
    dj.volume = 0.4
    for i in range(8):
        if i % 2 == 0:
            pass

# Pattern mode: specify rhythm and pitch explicitly
@loop(synth="kick_floor", beat=0.25)
def kick():
    dj.volume = 0.8
    dj.pattern = "x . x ."

@loop(synth="lead_acid", root="A3", scale="minor", beat=0.25)
def melody():
    dj.volume = 0.3
    dj.pattern = "0 . 3 . 5 ."

# Comments create space (reverb)
@loop(interval=4.0)
def pad():
    dj.volume = 0.1
    # ambient space
    # silence is music
    pass

3. Start watch mode

pycodedj watch demo.py

From here, just write code and save. Every save re-evaluates all loops.

4. Emergency stop

pycodedj panic

5. Stop one loop

pycodedj stop bass

6. Mute / unmute

pycodedj mute bass
pycodedj unmute bass

7. Set BPM and list synths

pycodedj bpm 128
pycodedj list-synths

Using dj.pattern

dj.pattern lets you specify rhythm and pitch explicitly.

from pycodedj import dj, loop

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

# Pitch pattern (integer = scale degree)
@loop(synth="bass_acid", root="A1", scale="minor", beat=0.25)
def bass():
    dj.volume = 0.35
    dj.pattern = "0 . 3 . 5 ."

# Chords and ties
@loop(synth="note", root="A1", scale="minor", beat=0.25)
def chord():
    dj.volume = 0.25
    dj.pattern = "0 . [0 3] ~ 5 . 3 ."
    # [0 3] = two-note chord, ~ = sustain the previous note one more step

Token reference:

@loop arguments for pattern mode:

Example Files

OSC Address Reference

Requirements

• Recommended OS: macOS (low-latency Core Audio) or Linux (Raspberry Pi 5, etc.)
• Python: 3.10 or later
• SuperCollider: 3.12 or later

Roadmap

• Python → SuperCollider OSC prototype
• Hot-reload live loop implementation (pycodedj watch)
• Sprint 1: Live stability (panic, SyntaxError recovery, mute/solo, status)
• Sprint 2: Music DSL (dj.pattern, @loop parameter expansion: synth, root, scale, beat)
• Sprint 3: Sound design and playability (SynthDef cleanup, bpm, list-synths)
• Sprint 4: Hydra visualiser integration

License

MIT + Commons Clause — free to use, modify, and perform (including paid live performances). Selling or commercially distributing the software itself is not permitted. See LICENSE for details.

Support

This project is maintained on a best-effort basis.

Bug reports and suggestions may be submitted through GitHub Issues, but responses and fixes are not guaranteed.