mirror of
https://github.com/got-feedBack/feedBack-desktop.git
synced 2026-08-11 19:29:32 +00:00
Clean release snapshot
This commit is contained in:
Byron Gamatos
@@ -0,0 +1,118 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user