pycodedj 0.5.0__tar.gz → 0.5.1__tar.gz

{pycodedj-0.5.0 → pycodedj-0.5.1}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.5.1] - 2026-05-08
+
+### Improvements
+
+- `examples/club_set.py` を `pattern()` / `synth=` ベースの重低音クラブセットに刷新。4つ打ちキック、ランブル、サブ、アシッド、ハット、フィル、空間ノイズを含む 11 ループ構成に変更
+- `pycodedj --version` を追加し、公開前チェックでパッケージバージョンを確認できるようにした
+
+### Docs
+
+- `docs/manual.ja.md` / `docs/manual.md` / `docs/manual.html` — ループ名と音色名の違いを明確化し、音色は `synth=` で指定することを追記
+- `docs/manual.ja.md` / `docs/manual.md` / `docs/manual.html` — `examples/club_set.py` の重低音クラブセットの使い方と主要レイヤー一覧を追加
+- `README.ja.md` / `README.md` — `examples/club_set.py` の説明を現在の 11 ループ構成に更新
+
 ## [0.5.0] - 2026-05-08
 
 ### Features

{pycodedj-0.5.0 → pycodedj-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodedj
-Version: 0.5.0
+Version: 0.5.1
 License: MIT License with Commons Clause
         
         "Commons Clause" License Condition v1.0
@@ -247,7 +247,7 @@ Token reference:
 | File | Contents |
 | :--- | :--- |
 | `examples/demo.py` | Intro demo: bass / melody / pad |
-| `examples/club_set.py` | EDM groove: 8 loops (kick, bass, hat, chords, pad) |
+| `examples/club_set.py` | Sub-heavy club set: 11 loops with kick, rumble, sub, acid, hats, and room noise |
 | `examples/sound_showcase.py` | All 30 synths — evaluate one at a time to audition |
 
 ---

{pycodedj-0.5.0 → pycodedj-0.5.1}/README.ja.md

@@ -185,7 +185,7 @@ def chord():
 | ファイル | 内容 |
 | :--- | :--- |
 | `examples/demo.py` | bass / melody / pad の 3 ループ入門デモ |
-| `examples/club_set.py` | EDM クラブグルーヴ（キック・ベース・ハット・コード・パッドを含む 8 ループ） |
+| `examples/club_set.py` | 重低音クラブセット（キック、ランブル、サブ、アシッド、ハット、空間ノイズを含む 11 ループ） |
 | `examples/sound_showcase.py` | 全 30 音色 — 1 音ずつ eval して確認できる |
 
 ---

{pycodedj-0.5.0 → pycodedj-0.5.1}/README.md

@@ -185,7 +185,7 @@ Token reference:
 | File | Contents |
 | :--- | :--- |
 | `examples/demo.py` | Intro demo: bass / melody / pad |
-| `examples/club_set.py` | EDM groove: 8 loops (kick, bass, hat, chords, pad) |
+| `examples/club_set.py` | Sub-heavy club set: 11 loops with kick, rumble, sub, acid, hats, and room noise |
 | `examples/sound_showcase.py` | All 30 synths — evaluate one at a time to audition |
 
 ---

{pycodedj-0.5.0 → pycodedj-0.5.1}/docs/manual.html

@@ -808,6 +808,8 @@ def kick_drum():
 
         <h3>@loop のパラメーター（pattern 用）</h3>
 
+        <p><strong>音色は <code>synth=</code> で指定します。</strong> <code>@loop("bass", synth="floor_kick")</code> と書くと、ループ名は <code>bass</code> のまま、鳴る音色だけが <code>floor_kick</code> になります。</p>
+
         <table>
           <thead><tr><th>引数</th><th>説明</th><th>例</th></tr></thead>
           <tbody>
@@ -818,6 +820,10 @@ def kick_drum():
           </tbody>
         </table>
 
+        <blockquote>
+          <p><code>@loop("kick", synth="floor_kick")</code> の <code>"kick"</code> はループ名、<code>"floor_kick"</code> は音色名です。<code>pycodedj eval demo.py::kick</code> や <code>pycodedj mute kick</code> ではループ名を使います。</p>
+        </blockquote>
+
         <h3>トリガーパターン — x と . だけで</h3>
 
         <p>音程なしで「リズムだけ」を指定したいときは <code>x</code> と <code>.</code> だけ使います。</p>
@@ -965,9 +971,29 @@ def atmosphere(volume=0.08):
 
         <pre data-lang="bash"><code id="code-s8-2">pycodedj watch myfile.py</code></pre>
 
+        <h3>重低音クラブセットを試す</h3>
+
+        <p><code>examples/club_set.py</code> は、クラブのフロアで鳴る低域を意識したサンプルです。4つ打ちキック、2・4拍のクラップ、オフビートハット、16分ハット、ランブル、サブベース、アシッドベース、スタブ、フィル、空間ノイズを重ねています。</p>
+
+        <pre data-lang="bash"><code id="code-s8-3">pycodedj watch examples/club_set.py</code></pre>
+
+        <p>主なループ名は次の通りです。<code>mute</code> / <code>unmute</code> で足し引きすると、クラブトラックのレイヤー構造がわかりやすくなります。</p>
+
+        <table>
+          <thead><tr><th>ループ名</th><th>役割</th><th>音色名</th></tr></thead>
+          <tbody>
+            <tr><td><code>kick</code></td><td>4つ打ちの土台</td><td><code>floor_kick</code></td></tr>
+            <tr><td><code>rumble</code></td><td>床鳴りする低域</td><td><code>bass_rumble</code></td></tr>
+            <tr><td><code>sub</code> / <code>floor</code></td><td>持続する重低音</td><td><code>sub_bass</code></td></tr>
+            <tr><td><code>acid</code></td><td>動くベースライン</td><td><code>bass_acid</code></td></tr>
+            <tr><td><code>offhat</code> / <code>hats</code></td><td>グルーヴの推進力</td><td><code>hat_ride</code>, <code>hat_engine</code></td></tr>
+            <tr><td><code>room</code></td><td>倉庫のような空間感</td><td><code>warehouse_air</code></td></tr>
+          </tbody>
+        </table>
+
         <h3>演奏中のコントロール</h3>
 
-        <pre data-lang="bash"><code id="code-s8-3">pycodedj mute bass        # bass を消音（停止はしない）
+        <pre data-lang="bash"><code id="code-s8-4">pycodedj mute bass        # bass を消音（停止はしない）
 pycodedj unmute bass      # bass の音量を元に戻す
 pycodedj panic            # すべてのループを即時停止
 pycodedj status           # ループの状態を確認</code></pre>
@@ -980,7 +1006,7 @@ pycodedj status           # ループの状態を確認</code></pre>
           <thead><tr><th>ファイル</th><th>内容</th></tr></thead>
           <tbody>
             <tr><td><code>examples/demo.py</code></td><td>bass / melody / pad の 3 ループ入門デモ</td></tr>
-            <tr><td><code>examples/club_set.py</code></td><td>EDM クラブグルーヴ（キック・ベース・ハット・コード・パッドを含む 8 ループ）</td></tr>
+            <tr><td><code>examples/club_set.py</code></td><td>重低音クラブセット（キック、ランブル、サブ、アシッド、ハット、空間ノイズを含む 11 ループ）</td></tr>
             <tr><td><code>examples/sound_showcase.py</code></td><td>全 30 音色 — 1 音ずつ eval して確認できる</td></tr>
           </tbody>
         </table>
@@ -992,16 +1018,35 @@ pycodedj status           # ループの状態を確認</code></pre>
       <section id="s9">
         <h2>9. 音色リファレンス</h2>
 
-        <p><code>@loop</code> の第一引数（ループ名）を変えると、SuperCollider 側で使う音色を選べます。全 30 音色を 1 音ずつ確認したい場合は <code>examples/sound_showcase.py</code> を使います。</p>
+        <p>PyCodeDJ では <strong>ループ名</strong> と <strong>音色名</strong> を分けて考えます。</p>
+
+        <ul>
+          <li>ループ名: <code>@loop("kick", ...)</code> の第一引数。<code>pycodedj eval demo.py::kick</code>、<code>mute</code>、<code>solo</code> などで指定する名前</li>
+          <li>音色名: SuperCollider 側のシンセ名。pattern ループでは <code>synth="floor_kick"</code> のように指定する名前</li>
+        </ul>
+
+        <p>音色を選ぶときは、下の表から音色名を選んで <code>synth=</code> に入れます。たとえば <code>@loop("bass", synth="floor_kick")</code> は、<code>bass</code> というループ名で <code>floor_kick</code> の音色を鳴らします。</p>
+
+        <p><code>pattern()</code> を使う場合は、<code>@loop("kick", synth="floor_kick")</code> のように、短いループ名と具体的な音色名を分けて書けます。</p>
 
-        <pre data-lang="bash"><code id="code-s9-1">pycodedj eval examples/sound_showcase.py::bass_acid
-pycodedj eval examples/sound_showcase.py::riser_noise
-pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
+        <p><code>pattern()</code> を使わない構造マッピングのループでは、互換性のためにループ名と同じ名前の音色があればそれが使われます。たとえば <code>@loop("bass_acid", interval=0.5)</code> は <code>bass_acid</code> 音色で鳴ります。</p>
+
+        <p>全 30 音色を 1 音ずつ確認したい場合は <code>examples/sound_showcase.py</code> を使います。</p>
+
+        <pre data-lang="bash"><code id="code-s9-1">pycodedj eval examples/sound_showcase.py::floor_kick
+pycodedj eval examples/sound_showcase.py::bass_acid
+pycodedj eval examples/sound_showcase.py::acid_lead</code></pre>
+
+        <p><code>examples/sound_showcase.py</code> では試聴しやすいように、ループ名を音色名と同じにしています。通常の pattern ループでは、次のように <code>synth=</code> にこの表の音色名を指定します。</p>
+
+        <pre data-lang="python"><code id="code-s9-2">@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")</code></pre>
 
         <h3>キック</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>kick_hard</code></td><td>硬めでアタックの強いキック</td></tr>
@@ -1013,7 +1058,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>ベース</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>bass_rumble</code></td><td>キック由来の低いランブル</td></tr>
@@ -1026,7 +1071,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>パーカッション</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>hat_engine</code></td><td>クローズ/オープンのハットグリッド</td></tr>
@@ -1042,7 +1087,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>コード・スタブ</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>chord_rave</code></td><td>明るいレイブスタブ</td></tr>
@@ -1057,7 +1102,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>リード・メロディー</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>acid_lead</code></td><td>アシッド系リード</td></tr>
@@ -1071,7 +1116,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>アトモスフィア</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>shimmer_pad</code></td><td>深いシマーパッド</td></tr>
@@ -1083,7 +1128,7 @@ pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
         <h3>FX</h3>
         <table>
           <thead>
-            <tr><th>ループ名</th><th>音</th></tr>
+            <tr><th>音色名</th><th>音</th></tr>
           </thead>
           <tbody>
             <tr><td><code>fx_impact</code></td><td>低いインパクト</td></tr>
@@ -1377,7 +1422,7 @@ pycodedj eval demo.py::pad --sc-port 57200</code></pre>
         <p><strong>使用例:</strong></p>
 
         <pre data-lang="bash"><code id="code-s12-2">pycodedj watch examples/demo.py
-pycodedj watch club_set.py --debounce 0.5
+pycodedj watch examples/club_set.py --debounce 0.5
 pycodedj watch myfile.py --sc-host 192.168.1.10</code></pre>
 
         <h3><code>pycodedj panic</code></h3>

{pycodedj-0.5.0 → pycodedj-0.5.1}/docs/manual.ja.md

@@ -505,6 +505,8 @@ def kick_drum():
 
 `pattern()` を使うループでは、`@loop` デコレータに次の引数を追加します。
 
+**音色は `synth=` で指定します。** `@loop("bass", synth="floor_kick")` と書くと、ループ名は `bass` のまま、鳴る音色だけが `floor_kick` になります。
+
 | 引数 | 説明 | 例 |
 | :--- | :--- | :--- |
 | `synth=` | 使うシンセ名 | `synth="floor_kick"` |
@@ -513,6 +515,7 @@ def kick_drum():
 | `dur=` | 1 ステップの長さ（秒） | `dur=0.25`（16 分音符相当） |
 
 > **ポイント:** `volume=` / `eq=` / `interval=` は pattern ループでも引き続き使えます。
+> `@loop("kick", synth="floor_kick")` の `"kick"` はループ名、`"floor_kick"` は音色名です。`pycodedj eval demo.py::kick` や `pycodedj mute kick` ではループ名を使います。
 
 ### トリガーパターン — x と . だけで
 
@@ -693,6 +696,25 @@ watch で起動すれば、保存するたびに変更したループだけが
 pycodedj watch myfile.py
 ```
 
+### 重低音クラブセットを試す
+
+`examples/club_set.py` は、クラブのフロアで鳴る低域を意識したサンプルです。4つ打ちキック、2・4拍のクラップ、オフビートハット、16分ハット、ランブル、サブベース、アシッドベース、スタブ、フィル、空間ノイズを重ねています。
+
+```bash
+pycodedj watch examples/club_set.py
+```
+
+主なループ名は次の通りです。`mute` / `unmute` で足し引きすると、クラブトラックのレイヤー構造がわかりやすくなります。
+
+| ループ名 | 役割 | 音色名 |
+| :--- | :--- | :--- |
+| `kick` | 4つ打ちの土台 | `floor_kick` |
+| `rumble` | 床鳴りする低域 | `bass_rumble` |
+| `sub` / `floor` | 持続する重低音 | `sub_bass` |
+| `acid` | 動くベースライン | `bass_acid` |
+| `offhat` / `hats` | グルーヴの推進力 | `hat_ride`, `hat_engine` |
+| `room` | 倉庫のような空間感 | `warehouse_air` |
+
 ### 演奏中のコントロール
 
 **ミュートとアンミュート**
@@ -729,7 +751,16 @@ pad          muted    0.08   200Hz
 
 ## 9. 音色リファレンス
 
-`@loop` の第一引数（ループ名）で、SuperCollider 側で使う音色が決まります。
+PyCodeDJ では **ループ名** と **音色名** を分けて考えます。
+
+- ループ名: `@loop("kick", ...)` の第一引数。`pycodedj eval demo.py::kick`、`mute`、`solo` などで指定する名前
+- 音色名: SuperCollider 側のシンセ名。pattern ループでは `synth="floor_kick"` のように指定する名前
+
+音色を選ぶときは、下の表から音色名を選んで `synth=` に入れます。たとえば `@loop("bass", synth="floor_kick")` は、`bass` というループ名で `floor_kick` の音色を鳴らします。
+
+`pattern()` を使う場合は、`@loop("kick", synth="floor_kick")` のように、短いループ名と具体的な音色名を分けて書けます。
+
+`pattern()` を使わない構造マッピングのループでは、互換性のためにループ名と同じ名前の音色があればそれが使われます。たとえば `@loop("bass_acid", interval=0.5)` は `bass_acid` 音色で鳴ります。
 
 全 30 音色を 1 音ずつ確認したい場合は `examples/sound_showcase.py` を使います。
 
@@ -739,11 +770,17 @@ pycodedj eval examples/sound_showcase.py::bass_acid
 pycodedj eval examples/sound_showcase.py::acid_lead
 ```
 
-`synth=` パラメーター（pattern 使用時）でも同じ名前を指定できます。
+`examples/sound_showcase.py` では試聴しやすいように、ループ名を音色名と同じにしています。通常の pattern ループでは、次のように `synth=` にこの表の音色名を指定します。
+
+```python
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
+```
 
 ### キック
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `kick_hard` | 硬めでアタックの強いキック |
 | `floor_kick` | 太い四つ打ちキック |
@@ -751,7 +788,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### ベース
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `bass_rumble` | 深い低音ランブル |
 | `bass_reese` | 揺れる Reese 系ベース |
@@ -760,7 +797,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### パーカッション
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `hat_engine` | クローズ/オープンのハットグリッド |
 | `hat_ride` | 長めのライド/オープンハット |
@@ -772,7 +809,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### コード・スタブ
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `chord_rave` | 明るいレイブスタブ |
 | `neon_stab` | ネオン系スタブコード |
@@ -783,7 +820,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### リード・メロディー
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `acid_lead` | アシッド系リード |
 | `lead_hoover` | Hoover 風リード |
@@ -793,7 +830,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### アトモスフィア
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `shimmer_pad` | 深いシマーパッド |
 | `warehouse_air` | 倉庫っぽい空気感 |
@@ -801,7 +838,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### FX
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `fx_impact` | 低いインパクト |
 | `riser_noise` | ノイズライザー（8 秒でスイープ上昇） |
@@ -1089,7 +1126,7 @@ pycodedj watch FILE [--sc-host HOST] [--sc-port PORT] [--debounce SECS]
 
 ```bash
 pycodedj watch examples/demo.py
-pycodedj watch club_set.py --debounce 0.5
+pycodedj watch examples/club_set.py --debounce 0.5
 ```
 
 ### `pycodedj panic`

{pycodedj-0.5.0 → pycodedj-0.5.1}/docs/manual.md

@@ -484,6 +484,8 @@ Tokens are separated by spaces. `"x . x ."` is a 4-step pattern.
 
 ### @loop arguments for pattern mode
 
+**Choose the sound with `synth=`.** `@loop("bass", synth="floor_kick")` keeps the loop name as `bass`, but plays the `floor_kick` synth.
+
 | Argument | Description | Example |
 | :--- | :--- | :--- |
 | `synth=` | Synth name | `synth="floor_kick"` |
@@ -492,6 +494,7 @@ Tokens are separated by spaces. `"x . x ."` is a 4-step pattern.
 | `dur=` | Step length in seconds | `dur=0.25` (sixteenth note) |
 
 > `volume=`, `eq=`, and `interval=` still work alongside pattern arguments.
+> In `@loop("kick", synth="floor_kick")`, `"kick"` is the loop name and `"floor_kick"` is the synth name. Use the loop name for commands such as `pycodedj eval demo.py::kick` and `pycodedj mute kick`.
 
 ### Trigger patterns — x and . only
 
@@ -670,6 +673,25 @@ Start watching and each save updates only the changed loops:
 pycodedj watch myfile.py
 ```
 
+### Try the sub-heavy club set
+
+`examples/club_set.py` is a low-end club-floor example. It layers a four-on-the-floor kick, clap on beats 2 and 4, offbeat hats, 16th-note hats, rumble, sub bass, acid bass, sparse stabs, fills, and room noise.
+
+```bash
+pycodedj watch examples/club_set.py
+```
+
+These are the main loop names. Use `mute` / `unmute` to bring layers in and out and hear how the groove is built.
+
+| Loop name | Role | Synth name |
+| :--- | :--- | :--- |
+| `kick` | Four-on-the-floor foundation | `floor_kick` |
+| `rumble` | Floor-shaking low end | `bass_rumble` |
+| `sub` / `floor` | Sustained sub pressure | `sub_bass` |
+| `acid` | Moving bassline | `bass_acid` |
+| `offhat` / `hats` | Groove and forward motion | `hat_ride`, `hat_engine` |
+| `room` | Warehouse-like space | `warehouse_air` |
+
 ### Live controls
 
 **Mute and unmute**
@@ -706,7 +728,16 @@ Delete the `@loop` block (decorator + function) and save. In watch mode, the loo
 
 ## 9. Sound Reference
 
-The first argument to `@loop` (the loop name) selects the synth on the SuperCollider side.
+PyCodeDJ has two related names:
+
+- Loop name: the first argument to `@loop("kick", ...)`. Use it with `pycodedj eval demo.py::kick`, `mute`, `solo`, and status commands.
+- Synth name: the SuperCollider synth name. Pattern loops set it with `synth="floor_kick"`.
+
+To choose a sound, pick a synth name from the tables below and put it in `synth=`. For example, `@loop("bass", synth="floor_kick")` creates a loop called `bass` that plays the `floor_kick` synth.
+
+With `pattern()`, you can keep these names separate: `@loop("kick", synth="floor_kick")` means the loop is called `kick`, and it plays the `floor_kick` synth.
+
+For non-pattern structure-mapping loops, PyCodeDJ keeps the older shorthand: if the loop name matches a synth name, that synth is used. For example, `@loop("bass_acid", interval=0.5)` plays the `bass_acid` synth.
 
 To audition all 30 synths one at a time, use `examples/sound_showcase.py`:
 
@@ -716,11 +747,17 @@ pycodedj eval examples/sound_showcase.py::bass_acid
 pycodedj eval examples/sound_showcase.py::acid_lead
 ```
 
-The same names work with the `synth=` argument in pattern mode.
+In `examples/sound_showcase.py`, loop names intentionally match synth names so each sound is easy to audition. In normal pattern loops, put one of the synth names below in `synth=`:
+
+```python
+@loop("kick", synth="floor_kick", dur=0.25)
+def kick():
+    pattern("x . x .")
+```
 
 ### Kick
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `kick_hard` | Hard, punchy kick |
 | `floor_kick` | Full four-on-the-floor kick |
@@ -728,7 +765,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### Bass
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `bass_rumble` | Deep low rumble |
 | `bass_reese` | Reese-style wobble bass |
@@ -737,7 +774,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### Percussion
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `hat_engine` | Closed/open hi-hat grid |
 | `hat_ride` | Long ride/open hat |
@@ -749,7 +786,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### Chords / Stabs
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `chord_rave` | Bright rave stab |
 | `neon_stab` | Neon-style stab chord |
@@ -760,7 +797,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### Lead / Melody
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `acid_lead` | Acid-style lead |
 | `lead_hoover` | Hoover-style lead |
@@ -770,7 +807,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### Atmosphere
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `shimmer_pad` | Deep shimmer pad |
 | `warehouse_air` | Industrial air texture |
@@ -778,7 +815,7 @@ The same names work with the `synth=` argument in pattern mode.
 
 ### FX
 
-| Name | Sound |
+| Synth name | Sound |
 | :--- | :--- |
 | `fx_impact` | Low impact hit |
 | `riser_noise` | Noise riser (8-second upward sweep) |
@@ -1058,7 +1095,7 @@ pycodedj watch FILE [--sc-host HOST] [--sc-port PORT] [--debounce SECS]
 
 ```bash
 pycodedj watch examples/demo.py
-pycodedj watch club_set.py --debounce 0.5
+pycodedj watch examples/club_set.py --debounce 0.5
 ```
 
 ### `pycodedj panic`

pycodedj-0.5.1/examples/club_set.py

@@ -0,0 +1,107 @@
+# PyCodeDJ club set — sub-heavy warehouse floor
+#
+# Load sc/synths.scd in SuperCollider, then run:
+#   pycodedj watch examples/club_set.py
+#
+# Club-focused design:
+# - steady four-on-the-floor kick for dancers
+# - clap on 2 and 4
+# - offbeat hats plus 16th-note motion
+# - bass notes locked to the kick with syncopated replies
+# - sustained sub and rumble layers for floor pressure
+# - sparse stabs and fills so the bass has room
+
+from pycodedj import loop, pattern
+
+
+# --- Drum engine: stable pulse first, variations second ---
+
+@loop("kick", synth="floor_kick", dur=0.117)
+def kick(volume=1.0, eq="edm", low=1.7, mid=0.78, high=0.82):
+    pattern(
+        "x . . . x . . . x . . . x . . . "
+        "x . . . x . . x x . . . x . . x"
+    )
+
+
+@loop("clap", synth="clap_snare", dur=0.117)
+def clap(volume=0.18, eq="pop", low=0.62, mid=0.85, high=0.98):
+    pattern(
+        ". . . . x . . . . . . . x . . . "
+        ". . . . x . . . . . . x x . x ."
+    )
+
+
+@loop("offhat", synth="hat_ride", dur=0.117)
+def offhat(volume=0.065, eq="edm", low=0.28, mid=0.78, high=1.0):
+    pattern(
+        ". . x . . . x . . . x . . . x . "
+        ". . x . . x x . . . x . . x x ."
+    )
+
+
+@loop("hats", synth="hat_engine", dur=0.0585)
+def hats(volume=0.075, eq="edm", low=0.3, mid=0.82, high=1.02):
+    pattern(
+        "x . x . x x x . x . x . x x x . "
+        "x x x . x . x x x . x x x . x ."
+    )
+
+
+# --- Low end: kick-locked weight with room-shaking sustain ---
+
+@loop("rumble", synth="bass_rumble", root="A1", scale="minor", dur=0.117)
+def rumble(volume=0.42, eq="edm", low=1.75, mid=0.58, high=0.32):
+    pattern(
+        "0 ~ . . 0 ~ . . 0 ~ . . 0 ~ . . "
+        "0 ~ . . 3 ~ . . 0 ~ . . 5 3 0 ."
+    )
+
+
+@loop("sub", synth="sub_bass", root="A1", scale="minor", dur=0.117)
+def sub(volume=0.58, eq="edm", low=1.85, mid=0.58, high=0.25):
+    pattern(
+        "0 ~ . 0 0 ~ . 0 0 ~ 3 . 0 ~ . 0 "
+        "0 ~ 0 . 3 ~ . 0 0 ~ 5 . 3 ~ 0 ."
+    )
+
+
+@loop("floor", synth="sub_bass", root="A1", scale="minor", dur=0.468)
+def floor(volume=0.22, eq="edm", low=1.9, mid=0.45, high=0.2):
+    pattern("0 ~ 0 ~ 0 ~ 0 ~")
+
+
+@loop("acid", synth="bass_acid", root="A1", scale="minor", dur=0.0585)
+def acid(volume=0.15, eq="edm", low=1.15, mid=0.88, high=0.72):
+    pattern(
+        "0 . 0 . 3 . 0 0 0 . 5 . 3 . 0 . "
+        "0 . 0 3 . 5 . 3 0 . 7 . 5 . 3 . "
+        "0 3 0 . 5 . 7 . 0 . 5 3 0 . 10 . "
+        "0 . 0 . 3 . 0 0 5 . 3 . 0 . 0 ."
+    )
+
+
+# --- Hooks and fills: sparse enough to leave room for the bass ---
+
+@loop("stabs", synth="chord_rave", root="A2", scale="minor", dur=0.117)
+def stabs(volume=0.095, eq="edm", low=0.55, mid=0.72, high=0.78):
+    pattern(
+        ". . . . [0 2 4] . . . . . . . [3 5 7] . . . "
+        ". . [5 7 9] . . . . . [0 2 4] . . . [3 5 7] . . ."
+    )
+
+
+@loop("fill", synth="tom_drum", root="A1", scale="minor", dur=0.0585)
+def fill(volume=0.09, eq="edm", low=1.15, mid=0.72, high=0.5):
+    pattern(
+        ". . . . . . . . . . . . . . . . "
+        ". . . . . . . . . . 0 . 3 5 7 10"
+    )
+
+
+@loop("room", synth="warehouse_air", root="A1", scale="minor", dur=0.468)
+def room(volume=0.08, eq="edm", low=1.2, mid=0.55, high=0.45):
+    # dark concrete reflections
+    # low frequency pressure
+    # distant system noise
+    pattern("0 . . . 0 . 3 . 0 . . . 5 . 3 .")

{pycodedj-0.5.0 → pycodedj-0.5.1}/pyproject.toml

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

{pycodedj-0.5.0 → pycodedj-0.5.1}/src/pycodedj/__init__.py

@@ -2,5 +2,5 @@
 
 from ._loop import loop, pattern
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 __all__ = ["loop", "pattern"]

{pycodedj-0.5.0 → pycodedj-0.5.1}/src/pycodedj/__main__.py

@@ -4,6 +4,7 @@ import argparse
 import sys
 from pathlib import Path
 
+from . import __version__
 from .block_parser import parse_blocks
 from .engine import Engine
 from .osc_bridge import OscBridge, OscEndpoint, OscError
@@ -11,6 +12,7 @@ from .osc_bridge import OscBridge, OscEndpoint, OscError
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="pycodedj")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     sub = parser.add_subparsers(dest="command")
 
     eval_p = sub.add_parser("eval", help="Evaluate a loop block and send OSC parameters")

pycodedj-0.5.0/examples/club_set.py

@@ -1,150 +0,0 @@
-# PyCodeDJ club groove — EDM edition
-#
-# 8 loops, each with a distinct code structure and sonic role.
-# Load sc/synths.scd in SuperCollider, then run:
-#   pycodedj watch examples/club_set.py
-#
-# Code structure → sound (by design):
-#
-#   kick_hard    depth=1, cf=0  →  580 Hz,  0.10 Hz LFO  (dark, static)
-#   sub_bass     depth=2, cf=1  →  960 Hz,  0.59 Hz LFO  (dark sub pulse)
-#   bass_acid    depth=5, cf=4  → 2100 Hz,  2.06 Hz LFO  (acid squelch)
-#   hat_engine   depth=7, cf=9  → 2860 Hz,  4.51 Hz LFO  (brightest, fastest)
-#   clap_snare   depth=6, cf=5  → 2480 Hz,  2.55 Hz LFO  (bright backbeat)
-#   chord_rave   depth=7, cf=7  → 2860 Hz,  3.53 Hz LFO  (rave stabs)
-#   lead_hoover  depth=5, cf=4  → 2100 Hz,  2.06 Hz LFO  reverb=0.15
-#   shimmer_pad  depth=1, cf=0  →  580 Hz,  0.10 Hz LFO  reverb=0.60
-
-from pycodedj import loop
-
-
-# --- Foundation: dead simple, bone-dry ---
-
-@loop("kick_hard", interval=1.0)
-def four_on_floor(volume=0.9, eq="edm", low=1.25):
-    hit = "down"
-    _ = hit
-
-
-# --- Sub: minimal pulse, barely more than the kick ---
-
-@loop("sub_bass", interval=1.0)
-def sub_layer(volume=0.4, eq="edm", low=1.45, high=0.7):
-    for beat in range(4):
-        sub = "low"
-        _ = sub
-
-
-# --- Groove: syncopated acid sequence with accents ---
-
-@loop("bass_acid", interval=0.5)
-def acid_line(volume=0.22, eq="edm", low=1.2, mid=1.05):
-    pattern = [
-        ("hit", True), ("skip", False), ("slide", True),
-        ("hit", True), ("skip", False), ("accent", True),
-        ("skip", False), ("slide", True),
-    ]
-    for step, (note, active) in enumerate(pattern):
-        if active:
-            for layer in range(2):
-                if layer == 0:
-                    out = note
-                else:
-                    out = f"{note}_tail"
-                _ = out
-
-
-# --- Hats: mechanical 16th-note grid ---
-
-@loop("hat_engine", interval=0.25)
-def closed_hats(volume=0.13, eq="edm", low=0.45, high=1.25):
-    for bar in range(2):
-        for tick in range(16):
-            if tick % 4 == 0:
-                if tick == 0:
-                    if bar == 0:
-                        hat = "anchor_a"
-                    else:
-                        hat = "anchor_b"
-                else:
-                    hat = "beat"
-            elif tick % 2 == 0:
-                hat = "up"
-            elif tick in (3, 7, 11, 15):
-                if bar == 0:
-                    hat = "ghost_a"
-                else:
-                    hat = "ghost_b"
-            else:
-                hat = "skip"
-            if tick in (6, 14):
-                hat = "open"
-            _ = hat
-
-
-# --- Backbeat: decisive 2 & 4 with fill on bar 4 ---
-
-@loop("clap_snare", interval=1.0)
-def backbeat(volume=0.26, eq="pop", low=0.75, high=1.15):
-    for bar in range(4):
-        for beat in range(4):
-            if beat == 1:
-                hit = "snap"
-            elif beat == 3:
-                if bar == 3:
-                    hit = "fill"
-                else:
-                    hit = "heavy"
-            else:
-                hit = "off"
-            _ = hit
-
-
-# --- Harmonic: stacked chord voices across phrases ---
-
-@loop("chord_rave", interval=2.0)
-def rave_stabs(volume=0.14, eq="edm", mid=0.9):
-    for phrase in range(4):
-        for voice in range(3):
-            for harmonic in range(2):
-                if phrase == 0:
-                    if voice == 0:
-                        chord = "root"
-                    elif voice == 1:
-                        chord = "fifth"
-                    else:
-                        chord = "octave"
-                elif phrase == 2:
-                    chord = "resolve"
-                else:
-                    chord = "hit"
-                _ = chord
-
-
-# --- Lead: phrase-based, slight air ---
-
-@loop("lead_hoover", interval=4.0)
-def hoover(volume=0.11, eq="edm", high=1.25):
-    # classic rave swell
-    # builds and drops
-    for phrase in range(4):
-        for step in range(3):
-            if phrase in (0, 2):
-                if step == 0:
-                    motion = "attack"
-                else:
-                    motion = "hold"
-                _ = motion
-
-
-# --- Space: pure atmosphere, no code at all ---
-
-@loop("shimmer_pad", interval=8.0)
-def shimmer(volume=0.06, eq="acoustic", low=0.65):
-    # wide hall reverb
-    # slow harmonic drift
-    # always underneath everything
-    # never noticed until it stops
-    # consonance without definition
-    # air between the notes
-    pass