Client Library

PotatoslicerPlayer
  PotatoslicerEngine
    Sequencer    -- advances row-by-row, dispatches note events
    Synth        -- 20-voice pool, delegates to SoundProviders
    Mixer        -- master volume + tanh soft-clip
    Activity     -- real-time metrics (RMS, peak, beat pulse)
  BufferedDevice -- ring buffer, background render thread

from potatoslicer.player import PotatoslicerPlayer

player = PotatoslicerPlayer(sample_rate=48000, num_voices=20, buffered=True)
player.start()

# Load and play
player.load_file("songs/chrome.json")
player.play(loop=True)
player.set_volume(0.3)

# Play from specific position
player.play_from(order_pos=2, row_pos=0)

# Export
player.export_wav("output.wav")
player.export_midi("output.mid")

# Playback position (synced to audio output)
order_pos, row_pos = player.playback_position

# Sound effects
player.enable_sfx()
player.play_sfx("confirm")

# MIDI output to external devices
player.enable_midi_output()  # virtual port "Potatoslicer"

player.shutdown()

from potatoslicer.engine import PotatoslicerEngine

engine = PotatoslicerEngine(sample_rate=48000, num_voices=20)
engine.set_song(song_dict)
engine.play()

# Render audio frames yourself
samples = engine.render(2048)  # float32 numpy array

# Direct note control
engine.note_on(channel=0, note="C-5", instrument_id="lead")
engine.note_off(channel=0, note="C-5")

player.enable_debug()
stats = player.get_debug_stats()
# {'avg_render_ms': 4.5, 'max_render_ms': 22.7,
#  'avg_buf_depth_ms': 299, 'min_buf_depth_ms': 171,
#  'underruns': 0, 'callbacks': 115}