mirror of
https://github.com/got-feedBack/feedBack-desktop.git
synced 2026-08-11 03:09:56 +00:00
119 lines
4.9 KiB
Markdown
119 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
1. **Renderer** (Slopsmith UI in a webview, talks to localhost
|
|
Python and to Electron via preload IPC).
|
|
2. **Electron main** (`src/main/`) — window lifecycle, IPC, plugin
|
|
manager, Python supervisor, audio bridge.
|
|
3. **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
|