pycodedj 0.1.2__tar.gz → 0.1.3__tar.gz

{pycodedj-0.1.2 → pycodedj-0.1.3}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.1.3] - 2026-05-07
+
+### Fixes
+
+- Add `readme = "README.md"` to `pyproject.toml` so PyPI shows the project description
+
 ## [0.1.2] - 2026-05-07
 
 ### Features

pycodedj-0.1.3/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: pycodedj
+Version: 0.1.3
+License: MIT License with Commons Clause
+        
+        "Commons Clause" License Condition v1.0
+        
+        The Software is provided to you by the Licensor under the License,
+        as defined below, subject to the following condition.
+        
+        Without limiting other conditions in the License, the grant of rights
+        under the License will not include, and the License does not grant to
+        you, the right to Sell the Software.
+        
+        For purposes of the foregoing, "Sell" means practicing any or all of
+        the rights granted to you under the License to provide to third
+        parties, for a fee or other consideration (including without limitation
+        fees for hosting or consulting/support services related to the
+        Software), a product or service whose value derives, entirely or
+        substantially, from the functionality of the Software. Any license
+        notice or attribution required by the License must also include this
+        Commons Clause License Condition notice.
+        
+        Software: PyCodeDJ
+        License: MIT
+        Licensor: Yuichi Kaneko
+        
+        -------------------------------------------------------------------------------
+        
+        MIT License
+        
+        Copyright (c) 2026 Yuichi Kaneko
+        
+        Permission is hereby granted, free of charge, to any person obtaining
+        a copy of this software and associated documentation files (the
+        "Software"), to deal in the Software without restriction, including
+        without limitation the rights to use, copy, modify, merge, publish,
+        distribute, sublicense, and/or sell copies of the Software, and to
+        permit persons to whom the Software is furnished to do so, subject to
+        the following conditions:
+        
+        The above copyright notice and this permission notice shall be included
+        in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+        IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+        CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+        TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+        SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+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'
+Description-Content-Type: text/markdown
+
+# PyCodeDJ
+
+[日本語版 README はこちら](https://github.com/kanekoyuichi/pycodedj/blob/main/README.ja.md)
+
+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 + Commons Clause — free to use, modify, and perform (including paid live performances). Selling or commercially distributing the software itself is not permitted. See [LICENSE](LICENSE) for details.

{pycodedj-0.1.2 → pycodedj-0.1.3}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "pycodedj"
-version = "0.1.2"
+version = "0.1.3"
 requires-python = ">=3.10"
+readme = "README.md"
 license = {file = "LICENSE"}
 dependencies = [
     "python-osc>=1.8",

pycodedj-0.1.2/PKG-INFO

@@ -1,60 +0,0 @@
-Metadata-Version: 2.4
-Name: pycodedj
-Version: 0.1.2
-License: MIT License with Commons Clause
-        
-        "Commons Clause" License Condition v1.0
-        
-        The Software is provided to you by the Licensor under the License,
-        as defined below, subject to the following condition.
-        
-        Without limiting other conditions in the License, the grant of rights
-        under the License will not include, and the License does not grant to
-        you, the right to Sell the Software.
-        
-        For purposes of the foregoing, "Sell" means practicing any or all of
-        the rights granted to you under the License to provide to third
-        parties, for a fee or other consideration (including without limitation
-        fees for hosting or consulting/support services related to the
-        Software), a product or service whose value derives, entirely or
-        substantially, from the functionality of the Software. Any license
-        notice or attribution required by the License must also include this
-        Commons Clause License Condition notice.
-        
-        Software: PyCodeDJ
-        License: MIT
-        Licensor: Yuichi Kaneko
-        
-        -------------------------------------------------------------------------------
-        
-        MIT License
-        
-        Copyright (c) 2026 Yuichi Kaneko
-        
-        Permission is hereby granted, free of charge, to any person obtaining
-        a copy of this software and associated documentation files (the
-        "Software"), to deal in the Software without restriction, including
-        without limitation the rights to use, copy, modify, merge, publish,
-        distribute, sublicense, and/or sell copies of the Software, and to
-        permit persons to whom the Software is furnished to do so, subject to
-        the following conditions:
-        
-        The above copyright notice and this permission notice shall be included
-        in all copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-        IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-        CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-        TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-        SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-License-File: LICENSE
-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'