pycodedj 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.3.0] - 2026-05-08
+
+### Features
+
+- `pycodedj panic` — 全アクティブループを即時停止。SuperCollider 側でシンセを解放し `~loops` / `~loopParams` を初期化する
+- `pycodedj mute <name>` — ループを消音（停止しない）。再評価時もミュート状態を維持
+- `pycodedj unmute <name>` — ミュート解除、音量を復元
+- `pycodedj solo <name>` — 対象ループ以外を全ミュート（CLI は OSC 直送、完全な状態管理は watch セッション内の `Engine.solo()` 推奨）
+- `pycodedj unsolo` — ソロ解除、solo 前のミュート状態に戻す
+- `pycodedj status` — アクティブループの名前・ミュート状態・音量・カットオフを表示
+
+### Improvements
+
+- `ParseResult` dataclass 導入 — `parse_blocks()` が SyntaxError 時に `ParseResult(ok=False, error=...)` を返すようになり、watch モードでコード編集中に構文エラーがあっても演奏中のループが止まらなくなった
+- `Engine` 内部状態を `LoopState` dataclass で管理 — `muted` / `muted_before_solo` フラグを保持し、mute/solo/unsolo の状態を正確に追跡
+- `eval_block` が OSC 送信成功後に内部状態を更新するよう修正（送信失敗時の状態不整合を解消）
+- `Engine.solo()` に未知のループ名ガードを追加（存在しない名前を渡しても全ループがミュートされない）
+- CLI `unmute` が SuperCollider に永続化された `amp=0` を上書きしてから voice_count を送るよう修正
+
+### Docs
+
+- README.md / README.ja.md — panic / mute / unmute / status のクイックリファレンスを追加、ロードマップの Sprint 1 を完了に更新
+- `docs/manual.md` / `docs/manual.ja.md` / `docs/manual.html` — セクション 12 に新コマンド 6 つの全リファレンスを追加
+
 ## [0.2.1] - 2026-05-08
 
 ### Docs

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodedj
-Version: 0.2.1
+Version: 0.3.0
 License: MIT License with Commons Clause
         
         "Commons Clause" License Condition v1.0
@@ -191,6 +191,33 @@ pycodedj watch demo.py
 
 From here, just write code and save.
 
+**5. 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**
+
+```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
+```
+
+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
@@ -275,11 +302,12 @@ External visualisers such as Hydra can receive the same parameters on a separate
 
 ## Roadmap
 
-- [x] Spec design and mapping design
-- [ ] Phase 0: Listening validation of mapping hypotheses
-- [x] Phase 1: Python → SuperCollider OSC prototype
-- [x] Phase 2: Hot-reload live loop implementation (`pycodedj watch`)
-- [ ] Phase 3: Hydra visualiser integration
+- [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
 
 ---
 

{pycodedj-0.2.1 → pycodedj-0.3.0}/README.ja.md

@@ -129,6 +129,33 @@ pycodedj watch demo.py
 
 あとはエディタでコードを書いて保存するだけです。
 
+**5. 緊急停止**
+
+```bash
+pycodedj panic
+```
+
+全アクティブループに停止信号を即時送信します。演奏中に問題が起きたときに使います。
+
+**6. ミュート / ソロ**
+
+```bash
+pycodedj mute bass        # ループを消音（停止はしない）
+pycodedj unmute bass      # 音量を元に戻す
+pycodedj solo pad         # pad 以外を全ミュート
+pycodedj unsolo           # ソロ解除、ミュート状態を元に戻す
+```
+
+注意: `mute` / `unmute` / `solo` / `unsolo` は OSC を直接 SuperCollider に送信します。完全な状態管理が必要な場合は watch セッション内で `Engine.mute()` / `Engine.solo()` を呼び出してください。
+
+**7. ループのステータス確認**
+
+```bash
+pycodedj status
+```
+
+アクティブなループの名前・ミュート状態・音量・フィルターカットオフを表示します。
+
 ---
 
 ## サンプルファイル
@@ -213,11 +240,12 @@ Hydra 等の外部ビジュアライザーへは同じパラメーターを別
 
 ## ロードマップ
 
-- [x] 仕様設計・マッピング設計
-- [ ] フェーズ0: マッピング仮説の聴取検証
-- [x] フェーズ1: Python → SuperCollider OSC プロトタイプ
-- [x] フェーズ2: ホットリロード・ライブループ実装（`pycodedj watch`）
-- [ ] フェーズ3: Hydra ビジュアライザー統合
+- [x] Python → SuperCollider OSC プロトタイプ
+- [x] ホットリロード・ライブループ実装（`pycodedj watch`）
+- [x] Sprint 1: ライブ安定性（`panic`, SyntaxError維持, `mute`/`solo`, `status`）
+- [ ] Sprint 2: 音楽DSL（`pattern()`, `sample()`, `@loop` パラメータ拡張, mapping モード）
+- [ ] Sprint 3: 音色・演奏性（SynthDef整理, `bpm`, `list-synths`）
+- [ ] Sprint 4: README・マニュアル刷新、Hydra ビジュアライザー統合
 
 ---
 

{pycodedj-0.2.1 → pycodedj-0.3.0}/README.md

@@ -129,6 +129,33 @@ pycodedj watch demo.py
 
 From here, just write code and save.
 
+**5. 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**
+
+```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
+```
+
+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
@@ -213,11 +240,12 @@ External visualisers such as Hydra can receive the same parameters on a separate
 
 ## Roadmap
 
-- [x] Spec design and mapping design
-- [ ] Phase 0: Listening validation of mapping hypotheses
-- [x] Phase 1: Python → SuperCollider OSC prototype
-- [x] Phase 2: Hot-reload live loop implementation (`pycodedj watch`)
-- [ ] Phase 3: Hydra visualiser integration
+- [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
 
 ---
 

{pycodedj-0.2.1 → pycodedj-0.3.0}/docs/manual.html

@@ -428,7 +428,7 @@ def my_sound(volume=0.4):
 
         <p>次のように表示されれば成功です。</p>
 
-        <pre data-lang="text"><code>usage: pycodedj [-h] {eval,watch} ...</code></pre>
+        <pre data-lang="text"><code>usage: pycodedj [-h] {eval,watch,panic,mute,unmute,solo,unsolo,status} ...</code></pre>
 
         <h3>SuperCollider をインストールする</h3>
         <p>SuperCollider の公式サイト（supercollider.github.io）からインストーラーをダウンロードします。</p>
@@ -1312,6 +1312,64 @@ pycodedj eval demo.py::pad --sc-port 57200</code></pre>
 pycodedj watch club_set.py --debounce 0.5
 pycodedj watch myfile.py --sc-host 192.168.1.10</code></pre>
 
+        <h3><code>pycodedj panic</code></h3>
+        <p>全アクティブループに即時停止信号を送ります。演奏中に問題が起きたとき、すべての音をすぐ止めたい場合に使います。SuperCollider 側で実行中のシンセをすべて解放し、ループ状態を初期化します。</p>
+
+        <pre data-lang="text"><code>pycodedj panic [--sc-host HOST] [--sc-port PORT]</code></pre>
+
+        <p><strong>使用例:</strong></p>
+        <pre data-lang="bash"><code id="code-s12-3">pycodedj panic</code></pre>
+
+        <h3><code>pycodedj mute</code></h3>
+        <p>ループを消音します（停止はしません）。ループは引き続き管理され、<code>unmute</code> で音量が復元します。</p>
+
+        <pre data-lang="text"><code>pycodedj mute NAME [--sc-host HOST] [--sc-port PORT]</code></pre>
+
+        <table>
+          <thead>
+            <tr><th>引数・オプション</th><th>説明</th><th>デフォルト</th></tr>
+          </thead>
+          <tbody>
+            <tr><td><code>NAME</code></td><td>ループ名</td><td>—</td></tr>
+            <tr><td><code>--sc-host</code></td><td>SuperCollider のホスト</td><td><code>127.0.0.1</code></td></tr>
+            <tr><td><code>--sc-port</code></td><td>SuperCollider の受信ポート番号</td><td><code>57120</code></td></tr>
+          </tbody>
+        </table>
+
+        <p><strong>使用例:</strong></p>
+        <pre data-lang="bash"><code id="code-s12-4">pycodedj mute bass</code></pre>
+
+        <p><strong>注意:</strong> CLI は OSC を直接 SuperCollider に送信します。ループを再評価してもミュート状態を維持したい場合は、watch セッション内で <code>Engine.mute()</code> を呼び出してください。</p>
+
+        <h3><code>pycodedj unmute</code></h3>
+        <p>ミュートしたループの音量を元に戻します。</p>
+
+        <pre data-lang="text"><code>pycodedj unmute NAME [--sc-host HOST] [--sc-port PORT]</code></pre>
+
+        <p><strong>使用例:</strong></p>
+        <pre data-lang="bash"><code id="code-s12-5">pycodedj unmute bass</code></pre>
+
+        <h3><code>pycodedj solo</code></h3>
+        <p><strong>CLI からはサポートされていません。</strong> Solo は watch プロセスの状態へのアクセスが必要です。watch セッション内で <code>Engine.solo()</code> を直接呼び出してください。</p>
+
+        <h3><code>pycodedj unsolo</code></h3>
+        <p><strong>CLI からはサポートされていません。</strong> watch セッション内で <code>Engine.unsolo()</code> を直接呼び出してください。</p>
+
+        <h3><code>pycodedj status</code></h3>
+        <p>アクティブなループの名前・ミュート状態・音量・フィルターカットオフを表示します。</p>
+
+        <pre data-lang="text"><code>pycodedj status [--sc-host HOST] [--sc-port PORT]</code></pre>
+
+        <p>出力形式:</p>
+        <pre data-lang="text"><code>Loop         State    Amp    Cutoff
+bass         playing  0.40   1340Hz
+pad          muted    0.15   200Hz</code></pre>
+
+        <p><strong>注意:</strong> <code>status</code> は <code>pycodedj watch</code> とは別プロセスで動作するため、watch プロセスの状態を読み取れません。CLI から単独で実行すると「no active loops」と表示されます。</p>
+
+        <p><strong>使用例:</strong></p>
+        <pre data-lang="bash"><code id="code-s12-6">pycodedj status</code></pre>
+
         <h3>ループの書き方</h3>
 
         <pre data-lang="python"><code id="code-s12-3">from pycodedj import loop
@@ -1465,7 +1523,7 @@ bridge = OscBridge(audio=OscEndpoint("127.0.0.1", 57120))
 engine = Engine(bridge=bridge)
 
 source = open("demo.py").read()
-blocks = {b.name: b for b in parse_blocks(source)}
+blocks = {b.name: b for b in parse_blocks(source).blocks}
 
 params = engine.eval_block(blocks["bass"])
 if params is not None:

{pycodedj-0.2.1 → pycodedj-0.3.0}/docs/manual.ja.md

@@ -117,7 +117,7 @@ pycodedj --help
 次のように表示されれば成功です。
 
 ```
-usage: pycodedj [-h] {eval,watch} ...
+usage: pycodedj [-h] {eval,watch,panic,mute,unmute,solo,unsolo,status} ...
 ```
 
 ### SuperCollider をインストールする
@@ -987,6 +987,90 @@ pycodedj watch club_set.py --debounce 0.5
 pycodedj watch myfile.py --sc-host 192.168.1.10
 ```
 
+### `pycodedj panic`
+
+全アクティブループに即時停止信号を送ります。
+
+```
+pycodedj panic [--sc-host HOST] [--sc-port PORT]
+```
+
+演奏中に問題が起きたとき、すべての音をすぐ止めたい場合に使います。SuperCollider 側で実行中のシンセをすべて解放し、ループ状態を初期化します。
+
+**使用例:**
+
+```bash
+pycodedj panic
+```
+
+### `pycodedj mute`
+
+ループを消音します（停止はしません）。ループは引き続き管理され、unmute で音量が復元します。
+
+```
+pycodedj mute NAME [--sc-host HOST] [--sc-port PORT]
+```
+
+| 引数・オプション | 説明 | デフォルト |
+| :--- | :--- | :--- |
+| `NAME` | ループ名 | — |
+| `--sc-host` | SuperCollider のホスト | `127.0.0.1` |
+| `--sc-port` | SuperCollider の受信ポート番号 | `57120` |
+
+**使用例:**
+
+```bash
+pycodedj mute bass
+```
+
+> **注意:** CLI は OSC を直接 SuperCollider に送信します。ループを再評価してもミュート状態を維持したい場合は、watch セッション内で `Engine.mute()` を呼び出してください。
+
+### `pycodedj unmute`
+
+ミュートしたループの音量を元に戻します。
+
+```
+pycodedj unmute NAME [--sc-host HOST] [--sc-port PORT]
+```
+
+**使用例:**
+
+```bash
+pycodedj unmute bass
+```
+
+### `pycodedj solo`
+
+> **CLI からはサポートされていません。** Solo は watch プロセスの状態へのアクセスが必要です。watch セッション内で `Engine.solo()` を直接呼び出してください。
+
+### `pycodedj unsolo`
+
+> **CLI からはサポートされていません。** watch セッション内で `Engine.unsolo()` を直接呼び出してください。
+
+### `pycodedj status`
+
+アクティブなループの名前・ミュート状態・音量・フィルターカットオフを表示します。
+
+```
+pycodedj status [--sc-host HOST] [--sc-port PORT]
+```
+
+出力形式:
+
+```
+Loop         State    Amp    Cutoff
+bass         playing  0.40   1340Hz
+pad          muted    0.15   200Hz
+```
+
+> **注意:** `status` は `pycodedj watch` とは別プロセスで動作するため、watch プロセスの状態を読み取ることができません。CLI から単独で実行すると「no active loops」と表示されます。
+
+**使用例:**
+
+```bash
+pycodedj status
+```
+
 ### ループの書き方
 
 ```python
@@ -1048,7 +1132,7 @@ bridge = OscBridge(audio=OscEndpoint("127.0.0.1", 57120))
 engine = Engine(bridge=bridge)
 
 source = open("demo.py").read()
-blocks = {b.name: b for b in parse_blocks(source)}
+blocks = {b.name: b for b in parse_blocks(source).blocks}
 
 params = engine.eval_block(blocks["bass"])
 if params is not None:

{pycodedj-0.2.1 → pycodedj-0.3.0}/docs/manual.md

@@ -117,7 +117,7 @@ pycodedj --help
 If you see this, you're good:
 
 ```
-usage: pycodedj [-h] {eval,watch} ...
+usage: pycodedj [-h] {eval,watch,panic,mute,unmute,solo,unsolo,status} ...
 ```
 
 ### Installing SuperCollider
@@ -985,6 +985,90 @@ pycodedj watch club_set.py --debounce 0.5
 pycodedj watch myfile.py --sc-host 192.168.1.10
 ```
 
+### `pycodedj panic`
+
+Sends an immediate stop signal to all active loops.
+
+```
+pycodedj panic [--sc-host HOST] [--sc-port PORT]
+```
+
+Use this when something goes wrong during a performance and you need everything to stop now. SuperCollider frees all running synths and clears its loop state.
+
+**Example:**
+
+```bash
+pycodedj panic
+```
+
+### `pycodedj mute`
+
+Silences a loop without stopping it. The loop continues to be tracked; unmuting restores its sound.
+
+```
+pycodedj mute NAME [--sc-host HOST] [--sc-port PORT]
+```
+
+| Argument / option | Description | Default |
+| :--- | :--- | :--- |
+| `NAME` | Loop name | — |
+| `--sc-host` | SuperCollider host | `127.0.0.1` |
+| `--sc-port` | SuperCollider receive port | `57120` |
+
+**Example:**
+
+```bash
+pycodedj mute bass
+```
+
+> **Note:** The CLI sends OSC directly to SuperCollider. For full state tracking (so that re-evaluating a loop while muted keeps it silent), call `Engine.mute()` within a watch session instead.
+
+### `pycodedj unmute`
+
+Restores sound for a muted loop.
+
+```
+pycodedj unmute NAME [--sc-host HOST] [--sc-port PORT]
+```
+
+**Example:**
+
+```bash
+pycodedj unmute bass
+```
+
+### `pycodedj solo`
+
+> **Not supported from the CLI.** Solo requires access to the watch process state. Call `Engine.solo()` directly within a watch session.
+
+### `pycodedj unsolo`
+
+> **Not supported from the CLI.** Call `Engine.unsolo()` directly within a watch session.
+
+### `pycodedj status`
+
+Prints the name, mute state, amplitude, and filter cutoff for each active loop.
+
+```
+pycodedj status [--sc-host HOST] [--sc-port PORT]
+```
+
+Output format:
+
+```
+Loop         State    Amp    Cutoff
+bass         playing  0.40   1340Hz
+pad          muted    0.15   200Hz
+```
+
+> **Note:** `status` runs in a separate process from `pycodedj watch` and cannot read the watch process state. It will show "no active loops" when invoked from the CLI.
+
+**Example:**
+
+```bash
+pycodedj status
+```
+
 ### Loop syntax
 
 ```python
@@ -1046,7 +1130,7 @@ bridge = OscBridge(audio=OscEndpoint("127.0.0.1", 57120))
 engine = Engine(bridge=bridge)
 
 source = open("demo.py").read()
-blocks = {b.name: b for b in parse_blocks(source)}
+blocks = {b.name: b for b in parse_blocks(source).blocks}
 
 params = engine.eval_block(blocks["bass"])
 if params is not None:

{pycodedj-0.2.1 → pycodedj-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pycodedj"
-version = "0.2.1"
+version = "0.3.0"
 requires-python = ">=3.10"
 readme = "README.md"
 license = {file = "LICENSE"}

{pycodedj-0.2.1 → pycodedj-0.3.0}/sc/synths.scd

@@ -669,6 +669,21 @@ s.waitForBoot({
     // OSCFunc with nil path receives every incoming OSC message and we filter by prefix.
     // var は SC では実行文より前に宣言しなければならないため、
     // すべての var をクロージャ先頭にまとめる。
+    // ── Panic handler ────────────────────────────────────────────────────────
+    // /pycodedj/panic: すべての Synth を即停止し ~loops / ~loopParams を初期化する。
+    // OSCFunc は再登録時に上書きされるため、スクリプト再実行時でも安全。
+    if (~pycodedjPanic.notNil) { ~pycodedjPanic.free };
+    ~pycodedjPanic = OSCFunc({ |msg, time, addr|
+        ~loops.keysValuesDo({ |name, synths|
+            if (synths.notNil) {
+                synths.do({ |synth| synth.set(\gate, 0) });
+            };
+        });
+        ~loops = Dictionary.new;
+        ~loopParams = Dictionary.new;
+        "PyCodeDJ panic: all loops stopped.".postln;
+    }, '/pycodedj/panic');
+
     if (~pycodedjOSC.notNil) {
         thisProcess.removeOSCRecvFunc(~pycodedjOSC);
     };

{pycodedj-0.2.1 → pycodedj-0.3.0}/src/pycodedj/__init__.py

@@ -2,5 +2,5 @@
 
 from ._loop import loop
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 __all__ = ["loop"]