potatoslicer-client 0.1.1

Potatoslicer — multi-engine audio synthesis library for Python

potatoslicer-client

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

Install

pip install potatoslicer-client

Quick Start

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:

{
  "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

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