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.

What's new in 0.6.0 Alpha 6

Security hardening, reliability fixes, and setup UX improvements across the desktop shell.

Security

• FFmpeg binaries now verified with SHA256 before use — macOS downloads are checked against the evermeet.cx checksum API; Windows downloads are checked against the gyan.dev companion .sha256 file. A corrupt or tampered download is rejected and removed before extraction.
• file:// and bare filesystem paths gated to debug builds — the download helpers no longer accept local file paths in release builds, closing a path-bypass vector.
• save_audio_file restricted to localhost URLs — the command now rejects any URL that isn't 127.0.0.1 or localhost, preventing SSRF from a compromised WebView.
• STEMDECK_PYTHON env var gated to debug builds — the override is no longer accepted in release builds.

Reliability

• Fix: save_audio_file now streams audio to disk with a timeout — previously the entire file was buffered in memory with no timeout. Large WAV files no longer risk OOM; hung responses no longer stall the async executor.
• Fix: pip subprocess tracked and killed on window close — if the window is closed during CUDA install, the pip child process is now terminated cleanly instead of being orphaned.
• Fix: runtime swap is now recoverable after a crash — if StemDeck is killed between the two rename steps of a runtime update, the old runtime is automatically restored on next launch instead of leaving a broken install.
• Fix: update_setup_config writes atomically — config.json is now written via a temp file + rename, preventing corruption on crash.
• Fix: download_file_with_progress calls sync_all() before rename on Windows — prevents corrupt archives after power loss.
• Fix: stop_backend no longer called twice on window close — removed the duplicate call from the ExitRequested handler.
• Fix: backend shutdown no longer blocks the main thread — stop_backend now drains the child process on a background thread, eliminating the "app not responding" heuristic on macOS/Windows.
• Fix: start_backend guards against concurrent invocations — a second call while startup is in progress now returns an error immediately instead of racing with the first.
• Fix: SSE listener deduplication on retry — rapid retries during runtime download no longer stack duplicate progress listeners, which caused incorrect progress bar values.
• Fix: stall timer no longer fires during local archive verification — the stall warning is now only active during network downloads.
• Fix: stall timer and progress status messages no longer write concurrently — when a stall is detected, the progress rotation is stopped before the stall message is written.

Architecture

• BackendState consolidated into a single Mutex — child and url are now co-located in a single Mutex<BackendStateInner>, enforcing the both-Some/both-None invariant atomically.
• Path override logic centralized — python_path, ffmpeg_path, and ffprobe_path now share a single env_path_override helper instead of duplicating the env-var + fallback pattern.

Setup UX (previously in alpha.5/alpha.6 drafts)

• Setup: stall detection for slow or unreachable downloads — warns after 30s of no progress; escalates after 60s.
• Setup: time-based progress messages during runtime download — rotates informational messages as time passes (30s, 90s milestones).
• Fix: Windows FFmpeg download no longer depends on PowerShell — uses a direct HTTP client. Closes #130.
• Fix: CUDA install errors show actionable messages — maps known failure patterns to user-friendly guidance. Closes #132.

Docs

• Fixed stale thcp/stemdeck repo URLs in README (3 locations).
• Updated CUDA manual-install example from cu121 to cu124.
• Fixed inconsistent Discord invite link.
• Added Environment Variables reference section to README.
• Added doc comments to all 14 Tauri command functions.

Installing

Drop the new .app into your Applications folder and launch. No manual migration steps required.

Artifact build

• macOS arm64 DMG built locally and verified before upload.

Artifact scan

• Windows portable packages were 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.