stemdeckapp/stemdeck

> [!IMPORTANT]

macOS users run this after installing:

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

macOS Gatekeeper will block the app on launch without this step. Proper code signing is planned for a future release.

[!NOTE]
Upgrading from a previous alpha? One manual cleanup recommended.
If you experienced stale library state or broken UI after a previous upgrade, delete the old WebKit cache before launching.

Option A -- Finder (recommended):

1. Open Finder
2. In the menu bar choose Go > Go to Folder... (or press Shift + Cmd + G)
3. Paste ~/Library/WebKit and press Enter
4. Find the folder named app.stemdeck.desktop and move it to Trash
5. Empty the Trash

Option B -- Terminal (advanced users only):

cd ~/Library/WebKit
rm -rf app.stemdeck.desktop

This is a one-time step. From this release onwards, the app clears it automatically on every upgrade.
Your library is safe -- it now lives in ~/Documents/StemDeck/ and is untouched by this cleanup.

What's new in 0.6.0 Alpha 1

Export Region

A new Export Region button sits in the footer transport bar, to the left of Export Mix. When a loop region is active, it trims and downloads the mix for that exact time range as WAV or MP3. The button is always visible but grayed out until a loop region is set, so it is easy to discover without cluttering the interface when not in use.

Windows: export loop no longer truncates query parameters

On Windows, the previous Export Region implementation opened download URLs via cmd /c start, which interprets & as a shell command separator. This silently dropped the end parameter from the URL, causing the backend to reject the request. The URL is now passed directly to explorer.exe, bypassing the shell entirely.

Library and stems now saved to ~/Documents/StemDeck

Your entire library (metadata, folders, mix state, stem preferences, and extracted audio files) now lives in ~/Documents/StemDeck/. This makes it visible in Finder, eligible for iCloud Drive backup, and means it survives any app reinstall or upgrade without any action on your part.

Previous versions stored everything inside ~/Library/Application Support/ which is hidden from Finder and wiped on reinstall.

WebKit stale-data eliminated automatically on macOS

Every upgrade used to leave stale cached state in ~/Library/WebKit/app.stemdeck.desktop, causing inconsistent behavior that required manually deleting three system folders. That folder is now cleared automatically on version change. No user action needed, ever.

Docker: permission error and silent stems fixed

• PermissionError on job creation -- Docker was creating the jobs/ bind-mount directory as root, blocking the app user from writing. Fixed with a gosu-based entrypoint that re-chowns the directory before dropping privileges.
• Silent stems from WAV uploads -- Professional WAVs (24-bit, 32-bit float, high sample rate) were passed directly to Demucs without normalisation, producing silent output. All uploads now go through ffmpeg normalisation to 16-bit 44.1 kHz stereo before separation.
• MP3 stem export crash -- Every MP3 stem download was crashing with an internal error. Fixed.

Ubuntu 26.04 / Python 3.14 compatibility

Ubuntu 26.04 ships Python 3.14 by default, but PyTorch 2.6.0 does not have wheels for it yet. run.sh now explicitly targets Python 3.12, and pyproject.toml enforces <3.14 so the installer never selects an incompatible interpreter.

Security hardening

• Stored XSS fixed -- YouTube titles, channel names, and tags are now HTML-escaped before being injected into the DOM. Previously a crafted video title could execute arbitrary JavaScript in the app.
• open_url restricted to http/https -- The Tauri command used to open external links now blocks file:///, ms-msdt:, and other non-web schemes.
• SSE endpoint now validates job IDs -- The /events endpoint was the only one missing the JOB_ID_RE check; it now returns 404 for malformed IDs.

Reliability fixes

• Background tasks held strongly -- The sweep loop and desktop parent watchdog are now kept in a reference set so the garbage collector cannot silently discard them mid-run.
• Pipeline errors clean up job directory -- A failed pipeline now deletes the partial job directory, the same cleanup already done on cancellation.
• Atomic job capacity check -- The capacity check and job registration now happen under the registry lock, closing a race that could let one extra job slip past the limit.
• Registry persistence serialises under lock -- Concurrent job removal no longer risks writing a stale snapshot to disk.

Desktop: audio playback fixed (macOS)

• On first load -- The waveform renderer was downloading every stem WAV twice (once for visuals, once for playback), saturating WKWebView's connection pool and causing audio to chop. The renderer now reuses wavesurfer's already-decoded buffers instead.
• After seeking -- Pressing play immediately after moving the playhead caused choppiness because WKWebView had not yet buffered audio at the new position. Playback now waits for all audio elements to signal readiness before starting.

Test coverage (+16 tests)

New tests cover: sections endpoint (happy path, 404, 422 invalid color/id), file upload (extension rejection, empty file, mp3, wav), 503 capacity for both YouTube and upload paths, SSE job ID validation, and SSE connection cap.

Installing

Drop the new .app into your Applications folder and launch. Your library will be migrated automatically on first launch. No manual steps required.

Artifact build

• macOS arm64 and x64 DMGs and runtime packs will be built and inspected on a macOS Woodpecker agent before upload.

Artifact scan

• Windows portable packages will be scanned with ClamAV in CI before upload.

Artifact build

• macOS arm64 and x64 DMGs and runtime packs were built and inspected on a macOS Woodpecker agent before upload.

Artifact scan

• Windows portable packages were scanned with ClamAV in CI before upload.