pycodedj 0.1.0__tar.gz

pycodedj-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          PKG_VERSION=$(python -c "
+          import tomllib
+          with open('pyproject.toml', 'rb') as f:
+              print(tomllib.load(f)['project']['version'])
+          ")
+          EXPECTED="v${PKG_VERSION}"
+          if [ "$TAG" != "$EXPECTED" ]; then
+            echo "Tag '$TAG' does not match pyproject.toml version '$EXPECTED'" >&2
+            exit 1
+          fi
+          echo "Version check passed: $TAG"
+
+      - name: Install build dependencies
+        run: pip install build hatchling
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pycodedj-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Secrets / Keys
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Logs
+*.log
+logs/
+
+# AI Agent
+.claude/settings.local.json
+.claude/todos/
+.claude/mcp*.json
+.codex
+.claude/
+AGENT.md
+
+# Claude Code
+CLAUDE.local.md
+CLAUDE.md
+
+# LLM / Vector DB
+*.chroma/
+chroma_db/
+vector_store/
+embeddings/
+*.faiss
+*.pkl
+
+# Agent state / memory
+agent_state/
+agent_memory/
+sessions/
+checkpoints/
+runs/
+
+# Temporary
+tmp/
+temp/
+.cache/

pycodedj-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0] - 2026-05-07
+
+### Features
+
+- `pycodedj eval FILE::LOOP` — evaluate a loop block and send OSC parameters to SuperCollider; prints feedback (`cutoff`, `lfo_rate`, `reverb_mix`, `voice_count`) on success and exits with code 1 on failure
+- `pycodedj watch FILE` — watch a file and re-evaluate all loops on every save; handles atomic saves (vim/Emacs rename-based writes) via `on_moved` and `on_created` in addition to `on_modified`; stops loops that are removed from the file between reloads
+- OSC bridge sends `voice_count` first so SuperCollider creates synths before receiving parameter updates
+- AST-based code analysis maps block nesting depth → filter cutoff, control-flow count → LFO rate, function count → polyphony voices, comment ratio → reverb depth
+- `sc/synths.scd` — SuperCollider synth definitions with a single `OSCFunc(nil path)` handler dispatching all `/pycodedj/loop/<name>/<param>` messages
+- `examples/demo.py` and `examples/club_set.py` bundled in the wheel as package data
+
+### Docs
+
+- `README.ja.md` and `README.md` with architecture overview, quick start, and OSC address reference
+- `docs/manual.ja.md` and `docs/manual.md` — beginner-friendly full manual covering setup, watch mode, code-to-sound mapping, club set example, and troubleshooting

pycodedj-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: pycodedj
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: python-osc>=1.8
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0; extra == 'watch'

pycodedj-0.1.0/README.ja.md

@@ -0,0 +1,211 @@
+# PyCodeDJ
+
+Pythonコードの構造をリアルタイムに音楽へ変換するライブコーディング環境。ファイルを保存するたびに演奏が変わる。
+
+---
+
+## コンセプト
+
+PyCodeDJ は「コードを書くこと」と「音を鳴らすこと」を直結させます。
+
+関数を増やせばポリフォニーが広がり、ネストを深くすればフィルターが開き、コメントを書き込めば空間が広がる。コードの構造そのものが楽器です。
+
+既存の Python ↔ SuperCollider ブリッジ（sc3nb・supriya）との違いは2点です。
+
+- **ホットリロード演奏** — ループを止めずにファイルを差し替える。保存が即座に音の変化になる。
+- **コード構造の可聴化** — AST解析で抽出した構造的特徴量（深さ・分岐数・関数数など）を音楽パラメーターへ自動変換する。
+
+---
+
+## アーキテクチャ
+
+```
+[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) | 余白の多さ＝空間の広さ |
+
+テンポ（BPM）と基音（Pitch）は演奏者が明示的に制御します。保存のたびに楽曲全体の土台が変わることを防ぐためです。
+
+---
+
+## インストール
+
+**必要なもの**
+
+- Python 3.10 以上
+- SuperCollider（scsynth が起動できる環境）
+
+```bash
+pip install 'pycodedj[watch]'
+```
+
+`[watch]` を付けると `pycodedj watch` コマンドも使えるようになります。
+
+開発用:
+
+```bash
+git clone https://github.com/yourname/pycodedj
+cd pycodedj
+pip install -e ".[dev]"
+```
+
+---
+
+## クイックスタート
+
+**1. SuperCollider を起動し、シンセを読み込む**
+
+SuperCollider IDE で `sc/synths.scd` を開いて実行します。
+
+**2. ライブコーディングファイルを用意する**
+
+```python
+# @loop bass interval=2.0
+def bass():
+    for i in range(8):
+        if i % 2 == 0:
+            pass
+
+# @loop melody interval=0.5
+def melody():
+    x = 1
+    y = 2
+    return x + y
+
+# @loop pad interval=4.0
+def pad():
+    # 空間を作る
+    # もう少し余白
+    pass
+```
+
+**3. ブロックを評価する**
+
+```bash
+pycodedj eval demo.py::bass
+```
+
+成功すると次のフィードバックが表示されます。
+
+```
+[pycodedj] bass  cutoff=418Hz  lfo=1.08Hz  reverb=0.00  voices=1
+```
+
+他のループはそのまま鳴り続けます。
+
+**4. watch モードでライブコーディング**
+
+毎回 eval を打つ代わりに、ファイル保存で全ループを自動再評価できます。
+
+```bash
+pycodedj watch demo.py
+```
+
+あとはエディタでコードを書いて保存するだけです。
+
+> **`interval` について（現在の MVP）:** `interval=2.0` のような値はパーサーが読み取りますが、現時点では OSC では送信されません。ループの繰り返し周期は SuperCollider 側の `TempoClock` で管理します。将来的に SC 側に interval を渡す仕組みを追加する予定です。
+
+---
+
+## サンプルファイル
+
+| ファイル | 内容 |
+| :--- | :--- |
+| `examples/demo.py` | bass / melody / pad の 3 ループ入門デモ |
+| `examples/club_set.py` | sub_bass / hat_engine / neon_stab / acid_lead / warehouse_air のクラブスタイルデモ |
+
+---
+
+## ライブコーディング例
+
+### ネストを深くするとフィルターが開く
+
+```python
+# @loop bass interval=2.0
+def bass():
+    for i in range(4):       # 制御フロー +1
+        for j in range(4):   # ネスト深さ +1、制御フロー +1
+            if i == j:       # ネスト深さ +1、制御フロー +1
+                pass
+```
+
+### 関数を増やすとポリフォニーが広がる
+
+```python
+# @loop chord interval=1.0
+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
+```
+
+---
+
+## OSC アドレス仕様
+
+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 | ポリフォニー声部数 |
+
+`<name>` はブロック名（`bass`、`melody` など）です。ループごとに独立したアドレスを持つため、複数ループが同じパラメーターを上書きしません。
+
+Hydra 等の外部ビジュアライザーへは同じパラメーターを別ポートに送信します。
+
+---
+
+## 動作環境
+
+- **推奨OS:** macOS（Core Audio の低遅延性を活用）または Linux（Raspberry Pi 5 等）
+- **Python:** 3.10 以上
+- **SuperCollider:** 3.12 以上
+
+---
+
+## ロードマップ
+
+- [x] 仕様設計・マッピング設計
+- [ ] フェーズ0: マッピング仮説の聴取検証
+- [x] フェーズ1: Python → SuperCollider OSC プロトタイプ
+- [x] フェーズ2: ホットリロード・ライブループ実装（`pycodedj watch`）
+- [ ] フェーズ3: Hydra ビジュアライザー統合
+
+---
+
+## ライセンス
+
+MIT

pycodedj-0.1.0/README.md

@@ -0,0 +1,211 @@
+# PyCodeDJ
+
+A live-coding environment that translates Python code structure into music in real time. Every save changes the performance.
+
+---
+
+## Concept
+
+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.
+
+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.
+
+---
+
+## Architecture
+
+```
+[Python engine]  →OSC→  [SuperCollider]  →audio out→  speakers
+      ↓ OSC
+  [Hydra etc.]  →video out→  screen
+```
+
+| Layer | Role | Technology |
+| :--- | :--- | :--- |
+| Control | Code analysis, scheduling, OSC dispatch | Python 3.10+, python-osc, watchdog |
+| Audio | Real-time sound synthesis | SuperCollider (scsynth) |
+| Visual | Music-synced visuals | Hydra or Pyxel |
+
+BPM clock is held by SuperCollider's `TempoClock`. Python only sends parameter updates over OSC; timing accuracy is delegated to SuperCollider.
+
+---
+
+## 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 |
+
+Tempo (BPM) and root pitch are controlled explicitly by the performer, to prevent the foundation of the piece from shifting on every save.
+
+---
+
+## Installation
+
+**Requirements**
+
+- Python 3.10 or later
+- SuperCollider (with scsynth available)
+
+```bash
+pip install 'pycodedj[watch]'
+```
+
+The `[watch]` extra enables the `pycodedj watch` command.
+
+Development install:
+
+```bash
+git clone https://github.com/yourname/pycodedj
+cd pycodedj
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+**1. Boot SuperCollider and load the synths**
+
+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():
+    for i in range(8):
+        if i % 2 == 0:
+            pass
+
+# @loop melody interval=0.5
+def melody():
+    x = 1
+    y = 2
+    return x + y
+
+# @loop pad interval=4.0
+def pad():
+    # make space
+    # a little more
+    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
+```
+
+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:
+
+```bash
+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
+
+| 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 |
+
+---
+
+## Live-Coding Examples
+
+### Deeper nesting opens the filter
+
+```python
+# @loop bass interval=2.0
+def bass():
+    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
+
+```python
+# @loop chord interval=1.0
+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
+```
+
+---
+
+## OSC Address Reference
+
+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 |
+
+`<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.
+
+External visualisers such as Hydra can receive the same parameters on a separate port.
+
+---
+
+## Requirements
+
+- **Recommended OS:** macOS (low-latency Core Audio) or Linux (Raspberry Pi 5, etc.)
+- **Python:** 3.10 or later
+- **SuperCollider:** 3.12 or later
+
+---
+
+## 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
+
+---
+
+## License
+
+MIT