stemdeckapp/stemdeck

[!IMPORTANT]
macOS first launch (no code signing yet). After dragging StemDeck to Applications, clear the Gatekeeper quarantine flag or macOS will say the app is damaged:

xattr -dr com.apple.quarantine /Applications/StemDeck.app

Optional: start from a clean slate. To reproduce a true first-run experience, open each path in Finder via the Go menu, then Go to Folder (Shift+Cmd+G), and move the folders to Trash:

• ~/Library/Application Support/StemDeck
• ~/Library/WebKit/app.stemdeck.desktop
• ~/Library/Caches/stemdeck
• ~/Library/Caches/app.stemdeck.desktop

You can also delete ~/Library/Preferences/app.stemdeck.desktop.plist the same way. This is optional; the app will work without it.

What's new in 0.8.0 Alpha 10

This release is a resilience and observability pass — no new user-facing features, but the backend is now far harder to crash, easier to diagnose, and self-heals from the failure modes that used to require manual cleanup.

Logging you can actually use

StemDeck now writes rotating log files instead of dropping everything to the console (and previously, sometimes leaking raw exceptions into the UI). Failed jobs are quarantined with evidence — the classified failure cause (out of memory, unsupported device, disk full, bad input, unknown) and the last lines of stderr are captured alongside per-stage timings, so a failure can be diagnosed after the fact instead of only in the moment.

GPU failures now retry on CPU automatically

If separation fails on your GPU (CUDA/MPS), StemDeck no longer just reports the failure — it automatically retries the same job on CPU. You'll see the job pause at "GPU failed — retrying on CPU (slower)..." and then finish, rather than needing to re-run it yourself. The job's history now records that it fell back, and which device it actually finished on.

Downloads retry instead of failing on the first hiccup

Fetching a track's metadata or the file itself used to fail outright on a transient network blip. Both steps now retry with backoff, and every network call has a socket timeout so a stalled connection can no longer hang a job indefinitely.

Registry can no longer corrupt itself

Multiple threads (the pipeline, the API, and the periodic sweep) all write the job registry concurrently. A shared temp file used to let two writers collide — on Windows this could throw a PermissionError outright. Registry writes are now atomic and collision-proof. Separately, jobs that finished right as the app crashed (stems written, metadata not yet saved) used to be permanently unrecoverable; they're now recovered on restart and self-heal their metadata.

Windows desktop shutdown fixed

The desktop app's watchdog — which shuts down the backend when its parent process exits — was calling a Windows API that hard-kills the process instead of asking it to shut down gracefully. Backend shutdown on Windows now goes through the same graceful signal path as everywhere else.

Installing

• macOS: drop the .app into Applications and launch (run the xattr command above first).
• Windows: unzip the downloaded .zip, then run StemDeck.exe from the extracted folder.
• Linux: download the .tar.gz for your hardware, extract it, and run ./StemDeck. Install the WebKitGTK + GTK runtime prerequisites first (FFmpeg is fetched automatically on first launch):

  sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
  

  The NVIDIA build additionally needs a working NVIDIA driver such that nvidia-smi reports your GPU (the CUDA runtime itself is bundled -- no separate CUDA toolkit install needed). If you have no NVIDIA GPU, use the CPU-only tarball.
• Docker / Unraid: install "StemDeck" from Unraid Community Applications, or pull ghcr.io/stemdeckapp/stemdeck:edge and map port 8000 plus the /app/jobs and /cache volumes. Add --runtime=nvidia for GPU acceleration. See the README for the full docker run command.