pycodedj 0.4.0__tar.gz → 0.5.1__tar.gz

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

@@ -1,5 +1,33 @@
 # 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
+
+- `pattern()` にコード構文 `[0 3]` を追加。1 ステップで複数の度数を同時発音できる
+- `pattern()` にタイ構文 `~` を追加。直前の音（または コード）を次のステップまで延長できる
+
+### Improvements
+
+- OSC パターン payload を v2 フォーマット（`"v2"` マーカー付き flat encoding）に統一
+- SC 側 `~setupPattern` を v2 専用 decode に変更。`\sustain` を `Pseq` で制御し、chord/tie の発音長を正確に管理
+- `encode_steps()` を `pattern.py` に追加。Python 内部の `list[PatternStep]` を OSC flat encoding に変換する
+
+---
+
 ## [0.4.0] - 2026-05-08
 
 ### Features

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodedj
-Version: 0.4.0
+Version: 0.5.1
 License: MIT License with Commons Clause
         
         "Commons Clause" License Condition v1.0
@@ -213,8 +213,24 @@ def kick():
 @loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
 def bass():
     pattern("0 . 3 . 5 .")
+
+# Chords and ties
+@loop("chord", synth="note", root="A1", scale="minor", dur=0.25)
+def chord():
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # [0 3] = two-note chord, ~ = sustain the previous note one more step
 ```
 
+Token reference:
+
+| Token | Meaning |
+| :--- | :--- |
+| `x` | Trigger (plays root note) |
+| `.` | Rest (silence) |
+| `0`, `1`, `2` … | Scale degree (pitch) |
+| `[0 3]` | Chord (multiple degrees simultaneously) |
+| `~` | Tie (extends the previous note/chord by one step) |
+
 `@loop` arguments for pattern mode:
 
 | Argument | Description |
@@ -231,7 +247,7 @@ def bass():
 | 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.4.0 → pycodedj-0.5.1}/README.ja.md

@@ -151,8 +151,24 @@ def kick():
 @loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
 def bass():
     pattern("0 . 3 . 5 .")
+
+# コードとタイ
+@loop("chord", synth="note", root="A1", scale="minor", dur=0.25)
+def chord():
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # [0 3] = 2音コード、~ = 直前の音を伸ばす
 ```
 
+`pattern()` のトークン一覧:
+
+| トークン | 意味 |
+| :--- | :--- |
+| `x` | トリガー（ルート音で鳴らす） |
+| `.` | 休符 |
+| `0`, `1`, `2` … | スケール度数 |
+| `[0 3]` | コード（複数の度数を同時発音） |
+| `~` | タイ（直前の音を 1 ステップ延長） |
+
 `@loop` に渡す引数:
 
 | 引数 | 説明 |
@@ -169,7 +185,7 @@ def bass():
 | ファイル | 内容 |
 | :--- | :--- |
 | `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.4.0 → pycodedj-0.5.1}/README.md

@@ -151,8 +151,24 @@ def kick():
 @loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
 def bass():
     pattern("0 . 3 . 5 .")
+
+# Chords and ties
+@loop("chord", synth="note", root="A1", scale="minor", dur=0.25)
+def chord():
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # [0 3] = two-note chord, ~ = sustain the previous note one more step
 ```
 
+Token reference:
+
+| Token | Meaning |
+| :--- | :--- |
+| `x` | Trigger (plays root note) |
+| `.` | Rest (silence) |
+| `0`, `1`, `2` … | Scale degree (pitch) |
+| `[0 3]` | Chord (multiple degrees simultaneously) |
+| `~` | Tie (extends the previous note/chord by one step) |
+
 `@loop` arguments for pattern mode:
 
 | Argument | Description |
@@ -169,7 +185,7 @@ def bass():
 | 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.4.0 → pycodedj-0.5.1}/docs/manual.html

@@ -801,11 +801,15 @@ def kick_drum():
             <tr><td><code>x</code></td><td>ここで音を鳴らす（トリガー）</td></tr>
             <tr><td><code>.</code></td><td>休符（無音）</td></tr>
             <tr><td><code>0</code>, <code>1</code>, <code>2</code> …</td><td>音を鳴らす + 音程（スケール度数）</td></tr>
+            <tr><td><code>[0 3]</code></td><td>コード（複数の度数を同時発音）</td></tr>
+            <tr><td><code>~</code></td><td>タイ（直前の音を 1 ステップ延長）</td></tr>
           </tbody>
         </table>
 
         <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>
@@ -816,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>
@@ -872,6 +880,28 @@ def melody():
           </tbody>
         </table>
 
+        <h3>コード — 複数の音を同時に鳴らす</h3>
+
+        <p>角括弧で複数の度数を囲むと、1 ステップで複数の音を同時に鳴らせます。</p>
+
+        <pre data-lang="python"><code id="code-s7-chord">@loop("chord", synth="note", root="C3", scale="minor", dur=0.5)
+def chord():
+    pattern("[0 2 4] . [0 3] .")
+    # [0 2 4]→C3+Eb3+G3（短三和音）, 休, [0 3]→C3+Eb3, 休</code></pre>
+
+        <p>コード内に書けるのは <strong>0 以上の整数のみ</strong>です。<code>.</code>・<code>x</code>・<code>~</code> は書けません。</p>
+
+        <h3>タイ — 音を伸ばす</h3>
+
+        <p><code>~</code> を使うと、直前の音（またはコード）を次のステップまで伸ばせます。</p>
+
+        <pre data-lang="python"><code id="code-s7-tie">@loop("bass", synth="note", root="A1", scale="minor", dur=0.25)
+def bass():
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # 0→A1, 休, [0 3]→和音（2ステップ持続）, 5→F2, 休, 3→D2, 休</code></pre>
+
+        <p><code>~</code> は単音・コードの直後にのみ書けます。先頭・<code>.</code> や <code>x</code> の直後は書けません。</p>
+
         <h3>実例: キック・ベース・メロディー</h3>
 
         <pre data-lang="python"><code id="code-s7-4">from pycodedj import loop, pattern
@@ -882,7 +912,8 @@ def kick():
 
 @loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
 def bass():
-    pattern("0 . 0 . 3 . 5 .")
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # 0→A1, 休, [0 3]→和音（2ステップ持続）, 5→F2, 休, 3→D2, 休
 
 @loop("melody", synth="acid_lead", root="A3", scale="minor", dur=0.5)
 def melody():
@@ -940,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>
@@ -955,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>
@@ -967,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>
+
+        <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::bass_acid
-pycodedj eval examples/sound_showcase.py::riser_noise
-pycodedj eval examples/sound_showcase.py::bell_rave</code></pre>
+        <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>
@@ -988,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>
@@ -1001,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>
@@ -1017,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>
@@ -1032,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>
@@ -1046,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>
@@ -1058,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>
@@ -1352,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.4.0 → pycodedj-0.5.1}/docs/manual.ja.md

@@ -496,6 +496,8 @@ def kick_drum():
 | `x` | ここで音を鳴らす（トリガー） |
 | `.` | 休符（無音） |
 | `0`, `1`, `2` … | 音を鳴らす + 音程（スケール度数） |
+| `[0 3]` | コード（複数の度数を同時に鳴らす） |
+| `~` | タイ（直前の音を次のステップまで伸ばす） |
 
 スペースで区切ると 1 ステップになります。`"x . x ."` なら 4 ステップのパターンです。
 
@@ -503,6 +505,8 @@ def kick_drum():
 
 `pattern()` を使うループでは、`@loop` デコレータに次の引数を追加します。
 
+**音色は `synth=` で指定します。** `@loop("bass", synth="floor_kick")` と書くと、ループ名は `bass` のまま、鳴る音色だけが `floor_kick` になります。
+
 | 引数 | 説明 | 例 |
 | :--- | :--- | :--- |
 | `synth=` | 使うシンセ名 | `synth="floor_kick"` |
@@ -511,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 と . だけで
 
@@ -584,6 +589,32 @@ def bass():
     # 0→C3, 休, x→C3, 休, 3→Eb3, 休, x→C3, 休
 ```
 
+### コード — 複数の音を同時に鳴らす
+
+`[0 3]` のように角括弧で複数の度数を囲むと、1 ステップで複数の音を同時に鳴らせます。
+
+```python
+@loop("chord", synth="note", root="C3", scale="minor", dur=0.5)
+def chord():
+    pattern("[0 2 4] . [0 3] .")
+    # [0 2 4]→C3+Eb3+G3（短三和音）, 休, [0 3]→C3+Eb3, 休
+```
+
+コード内に書けるのは **0 以上の整数のみ** です。`.`・`x`・`~` は書けません。
+
+### タイ — 音を伸ばす
+
+`~` を使うと、直前の音（または コード）を次のステップまで伸ばせます。
+
+```python
+@loop("bass", synth="note", root="A1", scale="minor", dur=0.25)
+def bass():
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # 0→A1, 休, [0 3]→和音（2ステップ分 持続）, 5→F2, 休, 3→D2, 休
+```
+
+`~` は単音・コードの直後にのみ書けます。先頭・`.` や `x` の直後は書けません。
+
 ### ルートノートの書き方
 
 `root=` にはノート名 + オクターブ番号を渡します。
@@ -596,7 +627,7 @@ def bass():
 | `"F#3"` | F♯3（`s` を使って `"Fs3"` とも書ける） |
 | `"C1"` | 低い C |
 
-### 実例: キックとベースとメロディー
+### 実例: キックとベースとコード
 
 ```python
 from pycodedj import loop, pattern
@@ -607,7 +638,8 @@ def kick():
 
 @loop("bass", synth="bass_acid", root="A1", scale="minor", dur=0.25)
 def bass():
-    pattern("0 . 0 . 3 . 5 .")
+    pattern("0 . [0 3] ~ 5 . 3 .")
+    # 0→A1, 休, [0 3]→2音コード（2ステップ持続）, 5→F2, 休, 3→D2, 休
 
 @loop("melody", synth="acid_lead", root="A3", scale="minor", dur=0.5)
 def melody():
@@ -664,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` |
+
 ### 演奏中のコントロール
 
 **ミュートとアンミュート**
@@ -700,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` を使います。
 
@@ -710,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` | 太い四つ打ちキック |
@@ -722,7 +788,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### ベース
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `bass_rumble` | 深い低音ランブル |
 | `bass_reese` | 揺れる Reese 系ベース |
@@ -731,7 +797,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### パーカッション
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `hat_engine` | クローズ/オープンのハットグリッド |
 | `hat_ride` | 長めのライド/オープンハット |
@@ -743,7 +809,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### コード・スタブ
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `chord_rave` | 明るいレイブスタブ |
 | `neon_stab` | ネオン系スタブコード |
@@ -754,7 +820,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### リード・メロディー
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `acid_lead` | アシッド系リード |
 | `lead_hoover` | Hoover 風リード |
@@ -764,7 +830,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### アトモスフィア
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `shimmer_pad` | 深いシマーパッド |
 | `warehouse_air` | 倉庫っぽい空気感 |
@@ -772,7 +838,7 @@ pycodedj eval examples/sound_showcase.py::acid_lead
 
 ### FX
 
-| 名前 | 音の特徴 |
+| 音色名 | 音の特徴 |
 | :--- | :--- |
 | `fx_impact` | 低いインパクト |
 | `riser_noise` | ノイズライザー（8 秒でスイープ上昇） |
@@ -1060,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`