Metadata-Version: 2.4
Name: pycodedj
Version: 0.1.4
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) · [Full Manual (EN)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.md) · [マニュアル (JA)](https://github.com/kanekoyuichi/pycodedj/blob/main/docs/manual.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.
