Getting Started

• - Python 3.11+
• - Linux (Ubuntu/Debian recommended). macOS may work with portaudio installed.
• - Audio output — speakers or headphones. The app needs a working audio device.

# install from pip
$ pip install potatoslicer

# launch the sequencer
$ python -m sequencer_app

Installs potatoslicer-client, pygame-ce, numpy, and sounddevice as dependencies.

To use just the audio engine in your own project (without the sequencer UI):

$ pip install potatoslicer-client

Then in your code:

from potatoslicer.player import PotatoslicerPlayer

player = PotatoslicerPlayer()
player.start()
player.load_file("songs/chrome.json")
player.play()
# ... your app runs ...
player.shutdown()

By default the app loads the bundled demo songs. Point it at your own folder of .json song files in one of four ways:

# 1. CLI flag (highest precedence)
$ python -m sequencer_app --songs-dir ~/my-songs

# 2. environment variable
$ export POTATOSLICER_SONGS_DIR=~/my-songs
$ python -m sequencer_app

# 3. click the DIR button in the song browser (persists
#    to ~/.config/potatoslicer/settings.json)

# 4. fallback: bundled demo songs

The DIR button opens an in-app directory browser with UP / HOME / SELECT / CANCEL buttons and remembers your choice across launches.

Audio is gracefully disabled if sounddevice/portaudio are missing. MIDI features require python-rtmidi.