pycodedj 0.3.0__tar.gz → 0.4.0__tar.gz

{pycodedj-0.3.0 → pycodedj-0.4.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.4.0] - 2026-05-08
+
+### Features
+
+- `pattern()` ヘルパー — `x`（トリガー）・`.`（休符）・整数（スケール度数）で構成したパターン文字列を SuperCollider に送信し `Pdef + Pbind` で再生する
+- `@loop` デコレータに `synth=`, `root=`, `scale=`, `dur=` 引数を追加。`pattern()` ループでシンセ・ルートノート・スケール・ステップ長を指定できる
+- `pycodedj_note` SynthDef を追加。音程パターン（度数を含む場合）は自動的にこのシンセで再生される
+- `send_pattern` / `send_pattern_stop` / `send_synth` を `OscBridge` に追加
+- SC 側: `~patterns` 辞書でアクティブな `Pdef` を追跡。`~startLoop` でパターン中のループに対して従来のシンセループが二重起動されないよう保護
+
+### Improvements
+
+- `block_parser._extract_pattern_call` を `ast.walk`（全ノード走査）から DFS preorder + ネストスコープ除外に変更。ネストされたヘルパー関数内の `pattern()` 呼び出しを誤検出しなくなった
+- パターン引数の検証を OSC 送信より前に行い、検証失敗時に状態が更新されないよう修正（アトミック更新）
+- パターンループは `voice_count=0` を送信し従来のシンセループを抑制。ミュート状態でも Pdef を停止しないよう `~applyLoopParams` を修正
+- 度数トークンがある場合は `synth=` 指定の有無にかかわらず `pycodedj_note` を使用（既存シンセは `freq` を消費しないため）
+
+### Docs
+
+- `docs/manual.ja.md` / `docs/manual.md` / `docs/manual.html` — マニュアル全面改訂。`pattern()` の使い方（第 7 章）を新設し、初心者向けに丁寧に再構成
+- `README.ja.md` / `README.md` — Sprint 2 機能（`pattern()`, `@loop` 拡張）の説明を追加、ロードマップの Sprint 2 を完了に更新
+
 ## [0.3.0] - 2026-05-08
 
 ### Features

{pycodedj-0.3.0 → pycodedj-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodedj
-Version: 0.3.0
+Version: 0.4.0
 License: MIT License with Commons Clause
         
         "Commons Clause" License Condition v1.0
@@ -72,12 +72,12 @@ A live-coding environment that translates Python code structure into music in re
 
 PyCodeDJ connects "writing code" directly to "making sound."
 
-Add more functions and the polyphony widens. Deepen nesting and the filter opens up. Fill in comments and the space grows. The structure of your code is the instrument.
+Add more `for` loops and the modulation speeds up. Deepen nesting and the filter opens up. Fill in comments and the space grows. Write `pattern("x . x .")` and that rhythm plays. Write `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 becomes an immediate sound change.
-- **Audible code structure** — structural features extracted via AST analysis (depth, branch count, function count, etc.) are automatically mapped to musical parameters.
+- **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 `pattern()` notation for rhythm and pitch. Mix them freely in the same file.
 
 ---
 
@@ -101,16 +101,14 @@ BPM clock is held by SuperCollider's `TempoClock`. Python only sends parameter u
 
 ## Code Structure → Music Parameter Mapping
 
-| Code feature | Music parameter | Musical rationale |
-| :--- | :--- | :--- |
-| Max nesting depth | Filter Cutoff (200–4000 Hz) | Deep structure = complexity = brightness |
-| 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 |
-| `eq=` / `low=` / `mid=` / `high=` arguments | Simple 3-band EQ | Per-loop tone shaping |
-
-Tempo (BPM) and root pitch are controlled explicitly by the performer, to prevent the foundation of the piece from shifting on every save.
+| Code feature | Music parameter |
+| :--- | :--- |
+| Max nesting depth | Filter Cutoff (200–4000 Hz) |
+| Control-flow count (if/for/while) | LFO rate (0.1–5.0 Hz) |
+| Function definition count | Polyphony voice count (1–4) |
+| Comment ratio | Reverb depth (0.0–0.8) |
+| `volume=` argument | Amplitude (0.0–1.0) |
+| `eq=` / `low=` / `mid=` / `high=` arguments | Simple 3-band EQ |
 
 ---
 
@@ -130,7 +128,7 @@ The `[watch]` extra enables the `pycodedj watch` command.
 Development install:
 
 ```bash
-git clone https://github.com/yourname/pycodedj
+git clone https://github.com/kanekoyuichi/pycodedj
 cd pycodedj
 pip install -e ".[dev]"
 ```
@@ -141,154 +139,111 @@ pip install -e ".[dev]"
 
 **1. Boot SuperCollider and load the synths**
 
-Open `sc/synths.scd` in the SuperCollider IDE and evaluate it.
+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**
 
 ```python
-from pycodedj import loop
+from pycodedj import loop, pattern
 
+# Code-structure mode: the shape of your code maps to sound
 @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(volume=0.3):
-    x = 1
-    y = 2
-    return x + y
+# pattern() mode: specify rhythm and pitch explicitly
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
+
+@loop("melody", synth="acid_lead", root="A3", scale="minor", dur=0.25)
+def melody():
+    pattern("0 . 3 . 5 .")
 
+# Comments create space (reverb)
 @loop("pad", interval=4.0)
-def pad(volume=0.15):
-    # make space
-    # a little more
+def pad(volume=0.1):
+    # ambient space
+    # silence is music
     pass
 ```
 
-**3. Evaluate a block**
-
-```bash
-pycodedj eval demo.py::bass
-```
-
-On success, feedback is printed immediately:
-
-```
-[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1  amp=0.40
-```
-
-Other loops keep playing without interruption.
-
-**4. Live-code with watch mode**
-
-Instead of running eval manually, use watch to re-evaluate all loops on every save:
+**3. Start watch mode**
 
 ```bash
 pycodedj watch demo.py
 ```
 
-From here, just write code and save.
+From here, just write code and save. Every save re-evaluates all loops.
 
-**5. Emergency stop**
+**4. Emergency stop**
 
 ```bash
 pycodedj panic
 ```
 
-Sends a stop signal to all active loops immediately. Use this if something goes wrong during a performance.
-
-**6. Mute / solo**
+**5. Mute / unmute**
 
 ```bash
-pycodedj mute bass        # silence a loop without stopping it
-pycodedj unmute bass      # restore its sound
-pycodedj solo pad         # mute all loops except pad
-pycodedj unsolo           # release solo, restore previous mute state
+pycodedj mute bass
+pycodedj unmute bass
 ```
 
-Note: `mute`, `unmute`, `solo`, and `unsolo` send OSC directly to SuperCollider. For full state management, call `Engine.mute()` / `Engine.solo()` from within a watch session.
-
-**7. Loop status**
-
-```bash
-pycodedj status
-```
-
-Prints the name, mute state, amplitude, and filter cutoff of each active loop.
-
 ---
 
-## Example Files
+## Using pattern()
 
-| File | Contents |
-| :--- | :--- |
-| `examples/demo.py` | Intro demo with bass / melody / pad |
-| `examples/club_set.py` | EDM groove (8 loops, kick → acid bass → rave stabs → hoover → shimmer) |
-| `examples/sound_showcase.py` | All 30 synths — evaluate one at a time to audition each sound |
-
----
-
-## Live-Coding Examples
-
-### Deeper nesting opens the filter
+`pattern()` lets you specify rhythm and pitch explicitly.
 
 ```python
-from pycodedj import loop
+from pycodedj import loop, pattern
 
-@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
-                pass
-```
-
-### More functions = more polyphony
+# Trigger pattern (x = hit, . = rest)
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
 
-```python
-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
+# Pitch pattern (integer = scale degree)
+@loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
+def bass():
+    pattern("0 . 3 . 5 .")
 ```
 
-### More comments = more space (reverb)
-
-```python
-from pycodedj import loop
+`@loop` arguments for pattern mode:
 
-@loop("pad", interval=4.0)
-def pad(volume=0.15):
-    # leave space here
-    # a little more
-    # silence is music
-    pass
-```
+| Argument | Description |
+| :--- | :--- |
+| `synth=` | Synth name to use |
+| `root=` | Root note (e.g. `"A3"`, `"C4"`) |
+| `scale=` | Scale name (e.g. `"minor"`, `"major"`, `"pentatonicMinor"`) |
+| `dur=` | Step length in seconds. `0.25` = sixteenth note at 60 BPM |
 
 ---
 
-## OSC Address Reference
+## Example Files
 
-Addresses used to communicate with SuperCollider.
+| File | Contents |
+| :--- | :--- |
+| `examples/demo.py` | Intro demo: bass / melody / pad |
+| `examples/club_set.py` | EDM groove: 8 loops (kick, bass, hat, chords, pad) |
+| `examples/sound_showcase.py` | All 30 synths — evaluate one at a time to audition |
 
-| Address | Type | Range | Parameter |
-| :--- | :--- | :--- | :--- |
-| `/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.
+## OSC Address Reference
 
-External visualisers such as Hydra can receive the same parameters on a separate port.
+| Address | Type | Parameter |
+| :--- | :--- | :--- |
+| `/pycodedj/loop/<name>/params` | int, float, float, float, float | `voice_count`, `cutoff`, `lfo_rate`, `reverb`, `amp` |
+| `/pycodedj/loop/<name>/pattern` | int, str, float, str, int… | Pattern data |
+| `/pycodedj/loop/<name>/pattern_stop` | — | Stop pattern |
+| `/pycodedj/loop/<name>/amp` | float | Amplitude (compatibility) |
 
 ---
 
@@ -305,9 +260,9 @@ External visualisers such as Hydra can receive the same parameters on a separate
 - [x] Python → SuperCollider OSC prototype
 - [x] Hot-reload live loop implementation (`pycodedj watch`)
 - [x] Sprint 1: Live stability (`panic`, SyntaxError recovery, `mute`/`solo`, `status`)
-- [ ] Sprint 2: Music DSL (`pattern()`, `sample()`, `@loop` parameter expansion, mapping modes)
-- [ ] Sprint 3: Sound design and playability (SynthDef cleanup, `bpm`, `list-synths`)
-- [ ] Sprint 4: README and manual refresh, Hydra visualiser integration
+- [x] Sprint 2: Music DSL (`pattern()`, `@loop` parameter expansion: `synth`, `root`, `scale`, `dur`)
+- [ ] Sprint 3: Sound design and playability (SynthDef cleanup, `bpm`, `list-synths`, `sample()`)
+- [ ] Sprint 4: Hydra visualiser integration
 
 ---
 

pycodedj-0.4.0/README.ja.md

@@ -0,0 +1,209 @@
+# PyCodeDJ
+
+[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 のコードを書くと、リアルタイムに音が変わるライブコーディング環境。ファイルを保存するたびに演奏が変わる。
+
+---
+
+## コンセプト
+
+PyCodeDJ は「コードを書くこと」と「音を鳴らすこと」を直結させます。
+
+`for` ループを増やすと音の揺らぎが速くなり、ネストを深くするとフィルターが開き、コメントを書き込むと空間が広がります。`pattern("x . x .")` と書けばそのリズムで音が鳴り、`pattern("0 . 3 . 5 .")` と書けば指定した音程で演奏されます。
+
+既存の Python ↔ SuperCollider ブリッジ（sc3nb・supriya）との違いは 2 点です。
+
+- **ホットリロード演奏** — ループを止めずにファイルを差し替える。保存が即座に音の変化になる
+- **2 つの演奏スタイル** — コードの構造から自動生成するモードと、`pattern()` で音程とリズムを明示指定するモードを自由に混在させられる
+
+---
+
+## アーキテクチャ
+
+```
+[Python エンジン]  →OSC→  [SuperCollider]  →音響出力→  スピーカー
+      ↓ OSC
+  [Hydra 等]  →映像出力→  スクリーン
+```
+
+| 層 | 役割 | 技術 |
+| :--- | :--- | :--- |
+| 制御層 | コード解析・スケジューリング・OSC 送出 | Python 3.10+, python-osc, watchdog |
+| 音響層 | リアルタイム音響合成 | SuperCollider (scsynth) |
+| 視覚層 | 音楽データに同期した映像生成 | Hydra または Pyxel |
+
+BPM クロックは SuperCollider 側の `TempoClock` が保持します。Python は「次のループで使う設定の更新」を OSC で送るだけで、タイミング精度は SuperCollider に委ねます。
+
+---
+
+## コード構造 → 音楽パラメーターのマッピング
+
+| コード特徴量 | 音楽パラメーター |
+| :--- | :--- |
+| ネストの深さ（最大） | フィルター Cutoff (200–4000 Hz) |
+| 制御フロー数（if/for/while） | LFO レート (0.1–5.0 Hz) |
+| 関数定義数 | ポリフォニー声部数 (1–4) |
+| コメント率 | リバーブ Depth (0.0–0.8) |
+| `volume=` 引数 | Amplitude (0.0–1.0) |
+| `eq=` / `low=` / `mid=` / `high=` 引数 | 簡易 3 バンド EQ |
+
+---
+
+## インストール
+
+**必要なもの**
+
+- Python 3.10 以上
+- SuperCollider（scsynth が起動できる環境）
+
+```bash
+pip install 'pycodedj[watch]'
+```
+
+`[watch]` を付けると `pycodedj watch` コマンドも使えます。
+
+開発用:
+
+```bash
+git clone https://github.com/kanekoyuichi/pycodedj
+cd pycodedj
+pip install -e ".[dev]"
+```
+
+---
+
+## クイックスタート
+
+**1. SuperCollider を起動してシンセを読み込む**
+
+SuperCollider IDE で `sc/synths.scd` を開き、Ctrl+A（Mac は Cmd+A）→ Ctrl+Enter（Mac は Cmd+Enter）で実行します。Post window に次が出れば準備完了です。
+
+```
+PyCodeDJ synths loaded. Ready. OSC port: 57120
+```
+
+**2. ライブコーディングファイルを用意する**
+
+```python
+from pycodedj import loop, pattern
+
+# コードの「構造」が音楽パラメーターになるモード
+@loop("bass", interval=2.0)
+def bass(volume=0.4):
+    for i in range(8):
+        if i % 2 == 0:
+            pass
+
+# pattern() でリズムと音程を明示指定するモード
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
+
+@loop("melody", synth="acid_lead", root="A3", scale="minor", dur=0.25)
+def melody():
+    pattern("0 . 3 . 5 .")
+
+# コメントで空間を作るモード
+@loop("pad", interval=4.0)
+def pad(volume=0.1):
+    # 背景の空気
+    # 余白
+    pass
+```
+
+**3. watch モードで起動する**
+
+```bash
+pycodedj watch demo.py
+```
+
+あとはエディタでコードを書いて保存するだけです。保存のたびに全ループが再評価されます。
+
+**4. 緊急停止**
+
+```bash
+pycodedj panic
+```
+
+**5. ミュート / アンミュート**
+
+```bash
+pycodedj mute bass
+pycodedj unmute bass
+```
+
+---
+
+## pattern() の使い方
+
+`pattern()` を使うと、リズムと音程を明示的に指定できます。
+
+```python
+from pycodedj import loop, pattern
+
+# トリガーパターン（x=鳴らす、.=休符）
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
+
+# 音程パターン（数字=スケール度数）
+@loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
+def bass():
+    pattern("0 . 3 . 5 .")
+```
+
+`@loop` に渡す引数:
+
+| 引数 | 説明 |
+| :--- | :--- |
+| `synth=` | 使うシンセ名 |
+| `root=` | ルートノート（例: `"A3"`, `"C4"`） |
+| `scale=` | スケール（例: `"minor"`, `"major"`, `"pentatonicMinor"`） |
+| `dur=` | 1 ステップの長さ（秒）。`0.25` で 16 分音符相当 |
+
+---
+
+## サンプルファイル
+
+| ファイル | 内容 |
+| :--- | :--- |
+| `examples/demo.py` | bass / melody / pad の 3 ループ入門デモ |
+| `examples/club_set.py` | EDM クラブグルーヴ（キック・ベース・ハット・コード・パッドを含む 8 ループ） |
+| `examples/sound_showcase.py` | 全 30 音色 — 1 音ずつ eval して確認できる |
+
+---
+
+## OSC アドレス仕様
+
+| アドレス | 型 | 対応パラメーター |
+| :--- | :--- | :--- |
+| `/pycodedj/loop/<name>/params` | int, float, float, float, float | `voice_count`, `cutoff`, `lfo_rate`, `reverb`, `amp` |
+| `/pycodedj/loop/<name>/pattern` | int, str, float, str, int… | パターンデータ |
+| `/pycodedj/loop/<name>/pattern_stop` | — | パターン停止 |
+| `/pycodedj/loop/<name>/amp` | float | 音量（互換用） |
+
+---
+
+## 動作環境
+
+- **推奨 OS:** macOS（Core Audio の低遅延性を活用）または Linux（Raspberry Pi 5 等）
+- **Python:** 3.10 以上
+- **SuperCollider:** 3.12 以上
+
+---
+
+## ロードマップ
+
+- [x] Python → SuperCollider OSC プロトタイプ
+- [x] ホットリロード・ライブループ実装（`pycodedj watch`）
+- [x] Sprint 1: ライブ安定性（`panic`, SyntaxError 維持, `mute`/`solo`, `status`）
+- [x] Sprint 2: 音楽 DSL（`pattern()`, `@loop` パラメータ拡張: `synth`, `root`, `scale`, `dur`）
+- [ ] Sprint 3: 音色・演奏性（SynthDef 整理, `bpm`, `list-synths`, `sample()`）
+- [ ] Sprint 4: Hydra ビジュアライザー統合
+
+---
+
+## ライセンス
+
+MIT + Commons Clause — 個人利用・改変・ライブパフォーマンス（有料公演含む）は自由です。ソフトウェアそのものの販売・有償サービス化は禁止しています。詳細は [LICENSE](LICENSE) を参照してください。