PyCodeDJ マニュアル

Python コードを書く。保存する。音が変わる。

1. PyCodeDJ とは

PyCodeDJ は Python のソースコードをライブ演奏に変換するツールです。ファイルを AST 解析し、@loop が付いた関数の構造と dj.* のメタ情報を読み取って SuperCollider に OSC を送ります。

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 ."

関数名がループ名になります。pycodedj eval demo.py::bass のように指定します。

2. インストールと起動

pip install 'pycodedj[watch]'

[watch] を付けると、保存時に自動更新する pycodedj watch が使えます。

SuperCollider IDE で sc/synths.scd を実行し、次の表示を確認します。

PyCodeDJ synths loaded. Ready. OSC port: 57120

pycodedj eval examples/demo.py::bass

低いベース音が鳴れば、Python から SuperCollider へメッセージが届いています。止めるときは pycodedj panic を使います。

3. ループの基本構文

from pycodedj import dj, loop

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

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

4. コード構造マッピング

dj.pattern がないループでは、関数本体の形が音になります。

5. 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 ."

dj.pattern = p1 のような変数参照は読み取りません。パターン文字列はループ本体に直接書いてください。

6. 複数ループ

@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
    # 広い空間
    pass

pycodedj watch examples/demo.py

7. 音色リファレンス

synth= に SuperCollider の音色名を指定します。関数名はループ名のままで、synth= は鳴らす音色だけを選びます。

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

全音色を 1 つずつ試聴:

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

Kick

Bass

Percussion

Chords / Stabs

Leads / Notes

Atmosphere / FX

8. CLI リファレンス

pycodedj eval FILE::LOOP
pycodedj watch examples/demo.py
pycodedj panic
pycodedj stop bass
pycodedj mute bass
pycodedj unmute bass
pycodedj bpm 128
pycodedj list-synths

9. トラブルシューティング

困ったときは、SuperCollider のサーバーが boot 済みか、sc/synths.scd を実行済みか、Post window に Ready. OSC port: 57120 が出ているかを最初に確認します。

音が出ない

1. SuperCollider IDE を開き、サーバーを boot します。
2. sc/synths.scd を全選択して実行します。
3. Post window に PyCodeDJ synths loaded. Ready. OSC port: 57120 が出ているか確認します。
4. pycodedj eval examples/demo.py::bass を実行します。

それでも鳴らない場合は、本体やオーディオインターフェイスのミュート、Post window の赤いエラー、別音色の確認を順番に見ます。

pycodedj eval examples/sound_showcase.py::kick_floor

OSC error

Python から SuperCollider にメッセージを送れない状態です。SuperCollider が起動しているか、サーバーが boot 済みか、OSC ポート番号が合っているかを確認します。

pycodedj eval examples/demo.py::bass --sc-port 57120
pycodedj watch examples/demo.py --sc-port 57120

loop not found

:: の後ろに書いた名前が、Python ファイル内の def の関数名と一致していません。synth="kick_floor" は音色名で、ループ名ではありません。

@loop(interval=2.0)
def bass():
    pass

pycodedj eval demo.py::bass

SyntaxError

: の付け忘れ、インデントのずれ、文字列の閉じ忘れを確認してください。watch モードでは、修正して保存すると再読み込みされ、直前に正常だったループは鳴り続けます。

pycodedj: command not found

pycodedj が未インストールか、別の Python 環境に入っています。再インストールし、必要なら Python 経由で実行します。

pip install 'pycodedj[watch]'
python -m pycodedj eval examples/demo.py::bass

音が大きすぎる、または小さすぎる

各ループの dj.volume を調整します。最初は 0.1 から 0.4 くらいが扱いやすいです。

10. 内部構成

PyCodeDJ は Python ソースを ast で解析します。loop, dj, pattern は実行時には no-op に近いヘルパーで、通常の Python ファイルとして import できます。

主なモジュール:

pycodedj/
├── _loop.py          # loop デコレータと dj 名前空間
├── block_parser.py   # @loop ブロックと dj メタ情報の抽出
├── analyzer.py       # コード特徴量抽出
├── mapper.py         # 特徴量から音楽パラメーターへの変換
├── pattern.py        # pattern 文字列パーサー
├── engine.py         # 評価パイプライン
├── osc_bridge.py     # OSC 通信
├── watcher.py        # ファイル監視
└── __main__.py       # CLI