Metadata-Version: 2.4
Name: potatoslicer-client
Version: 0.1.1
Summary: Potatoslicer — multi-engine audio synthesis library for Python
Author: Potatoslicer
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# potatoslicer-client

Multi-engine audio synthesis library for Python. Procedural audio from JSON song data — no audio files required.

## Install

```bash
pip install potatoslicer-client
```

## Quick Start

```python
from potatoslicer.player import PotatoslicerPlayer

player = PotatoslicerPlayer()
player.start()
player.load_file("path/to/song.json")
player.play()
player.set_volume(0.3)
player.stop()
player.shutdown()
```

## Sound Engines

Five synthesis providers, mixable in a single song:

| Provider | Type | Description |
|----------|------|-------------|
| `cadenza` | Waveform | Pulse, square, triangle, saw, noise with ADSR, vibrato, detune |
| `famiwave` | Pulse/Triangle/Noise | 4-bit quantized duty cycles, triangle staircase, LFSR noise |
| `supergausskit` | Gaussian Interp | BRR-style synthesis with gaussian filter, echo/delay |
| `nightfm` | 4-Op FM | 8 algorithms, per-operator ADSR, feedback, frequency multipliers |
| `wav_sampler` | Sample | WAV playback with pitch shifting, loop modes, trim |

## Song Format

Songs are JSON files. Each instrument picks its engine via the `type` field:

```json
{
  "title": "My Song",
  "tempo": 140,
  "rows_per_beat": 4,
  "order": [0, 1, 0, 2],
  "instruments": {
    "kick":  { "type": "cadenza", "waveform": "pulse", "attack": 0.001 },
    "bass":  { "type": "famiwave", "channel_type": "triangle" },
    "lead":  { "type": "nightfm", "algorithm": 4, "feedback": 3 },
    "pad":   { "type": "supergausskit", "echo_delay": 80 }
  },
  "patterns": {
    "0": [
      [{"channel": 0, "note": "C-1", "instrument": "kick"}],
      [], [], []
    ]
  }
}
```

## Architecture

```
PotatoslicerPlayer
  → PotatoslicerEngine
    → Sequencer (tracker-style pattern playback, Bresenham timing)
    → Synth (voice pool, per-channel rendering)
      → Providers (Cadenza, Famiwave, SuperGaussKit, NightFM, WavSampler)
    → Mixer (sum + tanh soft clip)
    → ActivityTracker (per-channel levels, FFT spectrum)
  → BufferedAudioDevice (threaded ring buffer → speakers)
```

## API Reference

```python
player = PotatoslicerPlayer(sample_rate=48000, num_voices=20)
player.start()                    # start audio device
player.load_file("song.json")    # load from file
player.load(song_dict)           # load from dict
player.play(loop=True)           # start playback
player.stop()                    # stop playback
player.set_volume(0.5)           # master volume 0.0-1.0
player.export_wav("out.wav")     # offline render to WAV
player.export_midi("out.mid")    # export as MIDI
player.shutdown()                # clean up audio device
```

## License

MIT
