pycodedj 0.1.3__tar.gz → 0.2.0__tar.gz

{pycodedj-0.1.3 → pycodedj-0.2.0}/.gitignore

@@ -50,9 +50,10 @@ logs/
 .claude/settings.local.json
 .claude/todos/
 .claude/mcp*.json
-.codex
+.codex/
 .claude/
 AGENT.md
+.agents/
 
 # Claude Code
 CLAUDE.local.md
@@ -77,3 +78,4 @@ runs/
 tmp/
 temp/
 .cache/
+docs/visualizer-*.html

{pycodedj-0.1.3 → pycodedj-0.2.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.2.0] - 2026-05-08
+
+### Breaking
+
+- `# @loop <name> interval=<sec>` コメント構文を廃止。`@loop("name", interval=sec)` デコレータ構文に移行
+- 既存のライブコーディングファイルはデコレータ構文への書き換えが必要
+
+### Features
+
+- `@loop("name", interval=sec)` デコレータ — ファイルをそのまま `python` で実行できる no-op デコレータとして `from pycodedj import loop` で提供
+- `volume=` 引数 — ループ関数のデフォルト引数として音量を直接指定できる（例: `def my_loop(volume=0.4):`）
+- Amplitude パラメーター（`amp`）を OSC で SuperCollider に送出。`/pycodedj/loop/<name>/params` は `voice_count, cutoff, lfo_rate, reverb, amp` の 5 値に拡張
+
+### Improvements
+
+- `sc/synths.scd` — `amp` パラメーターをすべての SynthDef と OSC ハンドラーに追加
+- `examples/club_set.py` — 6 層 14 ループ構成のクラブセットに刷新（foundation / movement / body / harmonic / space / texture）
+- `examples/demo.py` — 新デコレータ構文に更新
+
+### Docs
+
+- README.md / README.ja.md — 新デコレータ構文・`volume=` 引数・`amp` OSC パラメーターに全面更新
+- `docs/manual.md` / `docs/manual.ja.md` — 同上
+- `docs/index.html` — ライブデモアニメーションとコード例を新構文に更新
+
+## [0.1.4] - 2026-05-07
+
+### Fixes
+
+- Fix editable installs so `pycodedj.__main__` resolves from `src/pycodedj`
+- Fix SuperCollider OSC receiving and address parsing for `/pycodedj/loop/<name>/<param>` messages
+- Keep the SuperCollider OSC receiver active across repeated `synths.scd` reloads
+
 ## [0.1.3] - 2026-05-07
 
 ### Fixes

{pycodedj-0.1.3 → pycodedj-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodedj
-Version: 0.1.3
+Version: 0.2.0
 License: MIT License with Commons Clause
         
         "Commons Clause" License Condition v1.0
@@ -62,7 +62,7 @@ Description-Content-Type: text/markdown
 
 # PyCodeDJ
 
-[日本語版 README はこちら](https://github.com/kanekoyuichi/pycodedj/blob/main/README.ja.md)
+[日本語版 README はこちら](https://github.com/kanekoyuichi/pycodedj/blob/main/README.ja.md) · [Full Manual (EN)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.md) · [マニュアル (JA)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.ja.md)
 
 A live-coding environment that translates Python code structure into music in real time. Every save changes the performance.
 
@@ -107,6 +107,7 @@ BPM clock is held by SuperCollider's `TempoClock`. Python only sends parameter u
 | Control-flow count (if/for/while) | LFO rate (0.1–5.0 Hz) | More branches = faster modulation |
 | Function definition count | Polyphony voice count (1–4) | Functions = independent voices |
 | Comment ratio | Reverb depth (0.0–0.8) | More whitespace = more space |
+| `volume=` argument | Amplitude (0.0–1.0) | Direct performer control over loudness |
 
 Tempo (BPM) and root pitch are controlled explicitly by the performer, to prevent the foundation of the piece from shifting on every save.
 
@@ -144,20 +145,22 @@ Open `sc/synths.scd` in the SuperCollider IDE and evaluate it.
 **2. Write a live-coding file**
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(8):
         if i % 2 == 0:
             pass
 
-# @loop melody interval=0.5
-def melody():
+@loop("melody", interval=0.5)
+def melody(volume=0.3):
     x = 1
     y = 2
     return x + y
 
-# @loop pad interval=4.0
-def pad():
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
     # make space
     # a little more
     pass
@@ -172,7 +175,7 @@ pycodedj eval demo.py::bass
 On success, feedback is printed immediately:
 
 ```
-[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1
+[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1  amp=0.40
 ```
 
 Other loops keep playing without interruption.
@@ -187,8 +190,6 @@ pycodedj watch demo.py
 
 From here, just write code and save.
 
-> **Note on `interval` (current MVP):** Values like `interval=2.0` are parsed and stored, but are not yet sent over OSC. Loop repeat timing is managed by SuperCollider's `TempoClock`. A mechanism to pass interval to SC is planned for a future release.
-
 ---
 
 ## Example Files
@@ -196,7 +197,7 @@ From here, just write code and save.
 | File | Contents |
 | :--- | :--- |
 | `examples/demo.py` | Intro demo with bass / melody / pad |
-| `examples/club_set.py` | Club-style demo: sub_bass / hat_engine / neon_stab / acid_lead / warehouse_air |
+| `examples/club_set.py` | Layered club groove using kick_hard / bass_rumble / bass_reese and more |
 
 ---
 
@@ -205,8 +206,10 @@ From here, just write code and save.
 ### Deeper nesting opens the filter
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(4):       # control flow +1
         for j in range(4):   # depth +1, control flow +1
             if i == j:       # depth +1, control flow +1
@@ -216,21 +219,27 @@ def bass():
 ### More functions = more polyphony
 
 ```python
-# @loop chord interval=1.0
-def voice_a(): pass
-def voice_b(): pass
-def voice_c(): pass
-def voice_d(): pass
+from pycodedj import loop
+
+@loop("chord", interval=1.0)
+def chord(volume=0.2):
+    def voice_a(): pass
+    def voice_b(): pass
+    def voice_c(): pass
+    def voice_d(): pass
 ```
 
 ### More comments = more space (reverb)
 
 ```python
-# @loop pad interval=4.0
-# leave space here
-# a little more
-# silence is music
-def pad(): pass
+from pycodedj import loop
+
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
+    # leave space here
+    # a little more
+    # silence is music
+    pass
 ```
 
 ---
@@ -241,10 +250,12 @@ Addresses used to communicate with SuperCollider.
 
 | Address | Type | Range | Parameter |
 | :--- | :--- | :--- | :--- |
-| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | Filter Cutoff |
-| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO rate |
-| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | Reverb depth |
-| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | Polyphony voice count |
+| `/pycodedj/loop/<name>/params` | int, float, float, float, float | see parameter order | `voice_count`, `cutoff`, `lfo_rate`, `reverb`, `amp` |
+| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | Filter Cutoff (compatibility) |
+| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO rate (compatibility) |
+| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | Reverb depth (compatibility) |
+| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | Polyphony voice count (compatibility) |
+| `/pycodedj/loop/<name>/amp` | float | 0.0–1.0 | Amplitude (compatibility) |
 
 `<name>` is the loop name (e.g. `bass`, `melody`). Each loop has its own address namespace, so multiple loops never overwrite each other's parameters.
 

{pycodedj-0.1.3 → pycodedj-0.2.0}/README.ja.md

@@ -1,6 +1,6 @@
 # PyCodeDJ
 
-[English README](https://github.com/kanekoyuichi/pycodedj/blob/main/README.md)
+[English README](https://github.com/kanekoyuichi/pycodedj/blob/main/README.md) · [マニュアル (JA)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.ja.md) · [Full Manual (EN)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.md)
 
 Pythonコードの構造をリアルタイムに音楽へ変換するライブコーディング環境。ファイルを保存するたびに演奏が変わる。
 
@@ -45,6 +45,7 @@ BPMクロックは SuperCollider 側の `TempoClock` が保持します。Python
 | 制御フロー数（if/for/while） | LFO レート (0.1–5.0 Hz) | 分岐の多さ＝揺らぎの速さ |
 | 関数定義数 | ポリフォニー声部数 (1–4) | 関数＝独立した声部 |
 | コメント率 | リバーブ Depth (0.0–0.8) | 余白の多さ＝空間の広さ |
+| `volume=` 引数 | Amplitude (0.0–1.0) | 演奏者が直接音量を制御する |
 
 テンポ（BPM）と基音（Pitch）は演奏者が明示的に制御します。保存のたびに楽曲全体の土台が変わることを防ぐためです。
 
@@ -82,20 +83,22 @@ SuperCollider IDE で `sc/synths.scd` を開いて実行します。
 **2. ライブコーディングファイルを用意する**
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(8):
         if i % 2 == 0:
             pass
 
-# @loop melody interval=0.5
-def melody():
+@loop("melody", interval=0.5)
+def melody(volume=0.3):
     x = 1
     y = 2
     return x + y
 
-# @loop pad interval=4.0
-def pad():
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
     # 空間を作る
     # もう少し余白
     pass
@@ -110,7 +113,7 @@ pycodedj eval demo.py::bass
 成功すると次のフィードバックが表示されます。
 
 ```
-[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1
+[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1  amp=0.40
 ```
 
 他のループはそのまま鳴り続けます。
@@ -125,8 +128,6 @@ pycodedj watch demo.py
 
 あとはエディタでコードを書いて保存するだけです。
 
-> **`interval` について（現在の MVP）:** `interval=2.0` のような値はパーサーが読み取りますが、現時点では OSC では送信されません。ループの繰り返し周期は SuperCollider 側の `TempoClock` で管理します。将来的に SC 側に interval を渡す仕組みを追加する予定です。
-
 ---
 
 ## サンプルファイル
@@ -134,7 +135,7 @@ pycodedj watch demo.py
 | ファイル | 内容 |
 | :--- | :--- |
 | `examples/demo.py` | bass / melody / pad の 3 ループ入門デモ |
-| `examples/club_set.py` | sub_bass / hat_engine / neon_stab / acid_lead / warehouse_air のクラブスタイルデモ |
+| `examples/club_set.py` | kick_hard / bass_rumble / bass_reese などを重ねた多層クラブグルーヴ |
 
 ---
 
@@ -143,8 +144,10 @@ pycodedj watch demo.py
 ### ネストを深くするとフィルターが開く
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(4):       # 制御フロー +1
         for j in range(4):   # ネスト深さ +1、制御フロー +1
             if i == j:       # ネスト深さ +1、制御フロー +1
@@ -154,21 +157,27 @@ def bass():
 ### 関数を増やすとポリフォニーが広がる
 
 ```python
-# @loop chord interval=1.0
-def voice_a(): pass
-def voice_b(): pass
-def voice_c(): pass
-def voice_d(): pass
+from pycodedj import loop
+
+@loop("chord", interval=1.0)
+def chord(volume=0.2):
+    def voice_a(): pass
+    def voice_b(): pass
+    def voice_c(): pass
+    def voice_d(): pass
 ```
 
 ### コメントを増やすと空間（リバーブ）が広がる
 
 ```python
-# @loop pad interval=4.0
-# ここに余白を置く
-# もう少し置く
-# 静寂も音楽
-def pad(): pass
+from pycodedj import loop
+
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
+    # ここに余白を置く
+    # もう少し置く
+    # 静寂も音楽
+    pass
 ```
 
 ---
@@ -179,10 +188,12 @@ SuperCollider との通信に使うアドレスです。
 
 | アドレス | 型 | 値域 | 対応パラメーター |
 | :--- | :--- | :--- | :--- |
-| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | フィルター Cutoff |
-| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO レート |
-| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | リバーブ Depth |
-| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | ポリフォニー声部数 |
+| `/pycodedj/loop/<name>/params` | int, float, float, float, float | パラメーター順を参照 | `voice_count`, `cutoff`, `lfo_rate`, `reverb`, `amp` |
+| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | フィルター Cutoff（互換用） |
+| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO レート（互換用） |
+| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | リバーブ Depth（互換用） |
+| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | ポリフォニー声部数（互換用） |
+| `/pycodedj/loop/<name>/amp` | float | 0.0–1.0 | Amplitude（互換用） |
 
 `<name>` はブロック名（`bass`、`melody` など）です。ループごとに独立したアドレスを持つため、複数ループが同じパラメーターを上書きしません。
 

{pycodedj-0.1.3 → pycodedj-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # PyCodeDJ
 
-[日本語版 README はこちら](https://github.com/kanekoyuichi/pycodedj/blob/main/README.ja.md)
+[日本語版 README はこちら](https://github.com/kanekoyuichi/pycodedj/blob/main/README.ja.md) · [Full Manual (EN)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.md) · [マニュアル (JA)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.ja.md)
 
 A live-coding environment that translates Python code structure into music in real time. Every save changes the performance.
 
@@ -45,6 +45,7 @@ BPM clock is held by SuperCollider's `TempoClock`. Python only sends parameter u
 | Control-flow count (if/for/while) | LFO rate (0.1–5.0 Hz) | More branches = faster modulation |
 | Function definition count | Polyphony voice count (1–4) | Functions = independent voices |
 | Comment ratio | Reverb depth (0.0–0.8) | More whitespace = more space |
+| `volume=` argument | Amplitude (0.0–1.0) | Direct performer control over loudness |
 
 Tempo (BPM) and root pitch are controlled explicitly by the performer, to prevent the foundation of the piece from shifting on every save.
 
@@ -82,20 +83,22 @@ Open `sc/synths.scd` in the SuperCollider IDE and evaluate it.
 **2. Write a live-coding file**
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(8):
         if i % 2 == 0:
             pass
 
-# @loop melody interval=0.5
-def melody():
+@loop("melody", interval=0.5)
+def melody(volume=0.3):
     x = 1
     y = 2
     return x + y
 
-# @loop pad interval=4.0
-def pad():
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
     # make space
     # a little more
     pass
@@ -110,7 +113,7 @@ pycodedj eval demo.py::bass
 On success, feedback is printed immediately:
 
 ```
-[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1
+[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1  amp=0.40
 ```
 
 Other loops keep playing without interruption.
@@ -125,8 +128,6 @@ pycodedj watch demo.py
 
 From here, just write code and save.
 
-> **Note on `interval` (current MVP):** Values like `interval=2.0` are parsed and stored, but are not yet sent over OSC. Loop repeat timing is managed by SuperCollider's `TempoClock`. A mechanism to pass interval to SC is planned for a future release.
-
 ---
 
 ## Example Files
@@ -134,7 +135,7 @@ From here, just write code and save.
 | File | Contents |
 | :--- | :--- |
 | `examples/demo.py` | Intro demo with bass / melody / pad |
-| `examples/club_set.py` | Club-style demo: sub_bass / hat_engine / neon_stab / acid_lead / warehouse_air |
+| `examples/club_set.py` | Layered club groove using kick_hard / bass_rumble / bass_reese and more |
 
 ---
 
@@ -143,8 +144,10 @@ From here, just write code and save.
 ### Deeper nesting opens the filter
 
 ```python
-# @loop bass interval=2.0
-def bass():
+from pycodedj import loop
+
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
     for i in range(4):       # control flow +1
         for j in range(4):   # depth +1, control flow +1
             if i == j:       # depth +1, control flow +1
@@ -154,21 +157,27 @@ def bass():
 ### More functions = more polyphony
 
 ```python
-# @loop chord interval=1.0
-def voice_a(): pass
-def voice_b(): pass
-def voice_c(): pass
-def voice_d(): pass
+from pycodedj import loop
+
+@loop("chord", interval=1.0)
+def chord(volume=0.2):
+    def voice_a(): pass
+    def voice_b(): pass
+    def voice_c(): pass
+    def voice_d(): pass
 ```
 
 ### More comments = more space (reverb)
 
 ```python
-# @loop pad interval=4.0
-# leave space here
-# a little more
-# silence is music
-def pad(): pass
+from pycodedj import loop
+
+@loop("pad", interval=4.0)
+def pad(volume=0.15):
+    # leave space here
+    # a little more
+    # silence is music
+    pass
 ```
 
 ---
@@ -179,10 +188,12 @@ Addresses used to communicate with SuperCollider.
 
 | Address | Type | Range | Parameter |
 | :--- | :--- | :--- | :--- |
-| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | Filter Cutoff |
-| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO rate |
-| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | Reverb depth |
-| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | Polyphony voice count |
+| `/pycodedj/loop/<name>/params` | int, float, float, float, float | see parameter order | `voice_count`, `cutoff`, `lfo_rate`, `reverb`, `amp` |
+| `/pycodedj/loop/<name>/cutoff` | float | 200–4000 Hz | Filter Cutoff (compatibility) |
+| `/pycodedj/loop/<name>/lfo_rate` | float | 0.1–5.0 Hz | LFO rate (compatibility) |
+| `/pycodedj/loop/<name>/reverb` | float | 0.0–0.8 | Reverb depth (compatibility) |
+| `/pycodedj/loop/<name>/voice_count` | int | 1–4 | Polyphony voice count (compatibility) |
+| `/pycodedj/loop/<name>/amp` | float | 0.0–1.0 | Amplitude (compatibility) |
 
 `<name>` is the loop name (e.g. `bass`, `melody`). Each loop has its own address namespace, so multiple loops never overwrite each other's parameters.