open-stomp

An open-source library for the SORAN Dual Stomp Lite guitar pedal.

Version 0.6.1 · Rust and Python · Linux, macOS, Windows · Documentation · Changelog

open-stomp speaks the pedal's USB-MIDI and Bluetooth MIDI protocol, which was reverse engineered from the vendor's Stomp Manager app. It reads and edits presets, follows everything happening on the pedal, and imports NAM amp models and cab IRs with conversions that sound closer to the original than the official app's. This repository also holds the full protocol documentation.

The desktop editor Open Stomp Manager is built on it.

Compatibility. Tested on the Dual Stomp Lite, firmware V1.1.1. The Dual Stomp and Tiny Stomp share the firmware family and probably work too. Reports from owners are welcome.

Features

• Full protocol: parse and build every message the official app sends or receives: live CC/PC control, vendor SysEx, and the packed preset and settings records.
• State tracking: DeviceState follows all 99 presets, the live sound, looper, drum machine, tuner, settings and user slots, and describes each message in plain English (AMP · Mar J800 · GAIN = 64).
• Connection engine: finds the pedal, connects, follows hotplug, runs the startup sync and paces requests the way the pedal needs. Works over USB and Bluetooth LE.
• NAM and IR import: converts .nam models and WAV cab IRs for the pedal's user slots (results).
• Develop without a pedal: replay recorded sessions through the real engine.
• Python bindings: the same library from Python, fully typed.

The protocol layer has no I/O and no dependencies, so it can be used with any MIDI transport.

Installation

The crate isn't on crates.io yet. Add it from GitHub:

[dependencies]
open-stomp = { git = "https://github.com/JackMechem/open-stomp-lib", tag = "v0.6.1" }

To follow releases instead of pinning one, use branch = "stable" (newest release) or branch = "unstable" (newest release or pre-release); cargo update then moves you forward.

For Python ≥ 3.9, download the wheel for your platform from Releases and pip install it, or build from a checkout:

pip install ./bindings/python

Requirements: Rust 1.88 or newer. On Linux, install the ALSA and D-Bus headers (libasound2-dev libdbus-1-dev on Debian/Ubuntu, alsa-lib-devel dbus-devel on Fedora). macOS and Windows need nothing extra. The pedal is class compliant, so no driver is needed on any OS.

Feature	Default	Adds
device	✓	The connection engine (MIDI through midir)
ble	✓	Bluetooth LE MIDI (btleplug)
nam	✓	NAM model loading, inference and conversion; optimised IR conversion

default-features = false gives the protocol layer alone.

Quick start

use open_stomp::device::{Config, Device, Update};
use open_stomp::{DeviceState, Module};

let dev = Device::spawn(Config::default()); // finds and connects to the pedal by itself

// Change the live sound (nothing is stored until you save):
dev.select_preset(4);                        // P05
dev.set_head(Module::Amp, 8, true);          // AMP on, model 8 (Mar J800)
dev.set_param(Module::Amp, 0, 100);          // GAIN = 100

// Print everything that happens on the pedal:
let mut state = DeviceState::default();
while let Ok(update) = dev.recv() {
    match update {
        Update::Reset => state = DeviceState::default(),
        Update::Message { origin, bytes, .. } => {
            let ev = state.apply(&bytes, origin);
            println!("{:8} {} = {}", ev.category.label(), ev.subject, ev.value);
        }
        _ => {}
    }
}

The same in Python:

from open_stomp import Device, DeviceState

state = DeviceState()
with Device() as dev:
    for update in dev:
        if ev := state.feed(update):
            print(ev)                        # AMP      Mar J800 · GAIN = 64

No pedal? Replay a recorded session:

git clone https://github.com/JackMechem/open-stomp-lib && cd open-stomp-lib
cargo run --example monitor -- --replay captures/logs/01-main-session.log --speed 8

With a pedal plugged in, run cargo run --example monitor (add --listen to never send anything).

NAM and IR conversion

The pedal can't run a neural network. Each user amp slot holds two 512-tap filters with a fixed saturation curve between them, and each cab slot plays only the first 384 samples of an IR. Every import is an approximation.

open-stomp fits those filters to the original through a measured simulation of the pedal, instead of copying the official app's approach. The official app's algorithm is also available, reproduced exactly.

A bass DI re-amped through the pedal, compared with the original model and IR in software (rms error; lower is better):

	Official app	open-stomp
Overall tone (40 Hz–10 kHz)	9.4 dB	2.1 dB
Low end (40–160 Hz)	3.0 dB	3.3 dB
Closest to the original	8% of the recording	87%

This is the beginning of the README. Read the rest at the original. Read the full README ↗