Slopsmith Desktop Constitution

Core Principles

I. Wrap, Don't Fork

The desktop app is a shell around upstream Slopsmith. It MUST clone or bundle Slopsmith verbatim and run its server.py as a subprocess. We MUST NOT fork the Slopsmith codebase or carry private patches: if the desktop needs new behaviour from Slopsmith, the change goes upstream (gated by an env var or feature flag) before landing here.

II. Native Audio Is the Whole Point

The reason this app exists (vs. running Slopsmith in a browser) is low-latency audio with VST/AU/LV2 hosting, NAM, IRs, and pitch detection. The audio engine MUST be a JUCE C++ native addon (src/audio/) compiled via cmake-js, exposed to Electron through N-API (src/audio/NodeAddon.cpp) and bridged into the renderer via src/main/audio-bridge.ts. Audio code MUST NOT live in JS/TS.

III. Three-Process Architecture

The runtime has exactly three layers:

Renderer (Slopsmith UI in a webview, talks to localhost Python and to Electron via preload IPC).
Electron main (src/main/) — window lifecycle, IPC, plugin manager, Python supervisor, audio bridge.
Python subprocess (src/main/python.ts spawning slopsmith/server.py on port 18000+).

New features MUST fit one of these layers. Audio engine work is loaded from layer 2 via the native addon and MUST NOT bypass it.

IV. Bundle Everything Required to Run Offline

A first-run install MUST work without an internet connection: the Python interpreter, Slopsmith source tree, default IRs, and the default soundfont MUST be packaged via electron-builder's extraResources. Plugins are the exception (installed on demand into the user's config dir).

V. Reproducible Linux Builds Via DevContainer

Linux distribution builds MUST be reproducible against the ubuntu-22.04 GitHub Actions image. The DevContainer (.devcontainer/) and scripts/build-linux-release.sh are the canonical build path; ad-hoc npm run dist:linux on a developer's host is for development iteration only.

VI. Plugin Isolation From the App

Plugins MUST live in the user's config directory (~/.config/slopsmith-desktop/plugins/) and be managed via src/main/plugin-manager.ts. Updating the desktop app MUST NOT touch installed plugins; removing the desktop app MUST NOT delete them by default. Plugins are git clones of public repos; the plugin manager wraps git.

VII. Fail Soft on Audio Engine Absence

If the native audio addon fails to load (missing build, missing runtime libs, etc.), the rest of the app MUST keep working — Slopsmith UI, plugins, library browsing, all still functional. src/main/audio-bridge.ts already swallows load failures and returns audio:isAvailable === false; new features MUST follow the same pattern.

VIII. Cross-Platform Means All Three (NON-NEGOTIABLE)

We support Windows 10+, macOS 12+, and Linux. Every feature MUST ship working code paths for all three. Per-OS audio backends: ASIO/CoreAudio/JACK+ALSA. VST3 everywhere; AU on macOS; LV2 on Linux. Per-OS distribution targets: AppImage+deb, dmg+zip, NSIS exe.

Operational Constraints

Stack: Electron + TypeScript (main/renderer wiring), JUCE C++ (audio engine), Python 3.12 (Slopsmith subprocess), CMake 3.22+.
Native Modules: slopsmith_audio.node built via cmake-js, unpacked from asar at runtime (asarUnpack in package.json.build).
Resources: resources/{slopsmith,python,bin,default-irs, soundfonts} are extra-resourced into the packaged app.
Server port range: 18000+ (chosen to avoid colliding with a Docker Slopsmith on 8000 — see src/main/python.ts).
App ID: com.byron.slopsmith-desktop.
NAM: NeuralAmpModelerCore vendored at src/audio/third_party/NAM/; NAM support is conditional on the vendored tree being present (CMakeLists.txt).

Development Workflow

npm run dev — TS rebuild + Electron launch (uses the system Python, not the bundled one).
npm run build:audio — JUCE native addon (Release).
npm run dist:{linux,mac,win} — full bundle + electron-builder.
New audio capabilities go through SignalChain and a new *Processor C++ class; the addon API is in src/audio/NodeAddon.cpp.
Plugin manager UI changes go in src/renderer/plugin-manager/.
Splash screen / startup polling lives in src/main/main.ts and src/main/splash*.ts; respect the 5-minute startup deadline and the 700 ms poll interval already documented there.

Governance

This repo is one of several in the Slopsmith ecosystem. The shared workspace at ~/Repositories/slopsmith-workspace/ coordinates cross-repo work. Constitution amendments here MUST consider whether the upstream Slopsmith repo needs a parallel change (Principle I). The desktop app is a downstream consumer of upstream Slopsmith, upstream slopsmith-demucs-server (optional, configured by the user), and the per-feature plugin repos (optional, installed by the user).

Version: 1.0.0 | Ratified: 2026-05-09 | Last Amended: 2026-05-09

4.9 KiB Raw Blame History