Desktop App
SpinDeck ships a Tauri 2 desktop shell for macOS, Windows, and Linux. The desktop build loads the web SPA in a native WebView and exposes playlist import / playback via Tauri invoke and cover:// — recommended on macOS for full playback control.
Architecture (desktop)
| Piece | Responsibility |
|---|---|
| Tauri WebView | Hosts the SPA (frontendDist / Vite in dev) |
Rust commands/ | invoke handlers for import and playback |
Rust cover | cover:// cover-art proxy |
Rust playlist/ | QQ / NetEase / Kugou import providers |
Rust playback/ | Local music-app control (macOS AppleScript / open) |
See Architecture for the monorepo diagram and IPC table, Performance & Visuals for the 3D shelf memory / atmosphere policy, and System Requirements for OS / hardware floors. App package notes: apps/desktop/README.md.
Download
Download pre-built desktop installers from GitHub Releases:
v1.0.0-beta.8 (latest)
Pick the asset for your platform (.dmg / .app on macOS, .msi / .exe on Windows, etc.). Release builds bundle the SPA and Rust desktop features — Node.js is no longer required on the user's machine.
What's new in v1.0.0-beta.8
- System media controls ↔ tonearm sync — After pause then resume via Control Center / headset controls, the tonearm lowers again instead of staying raised
- Reliable stop when leaving playback — Always send pause on desktop when exiting to the shelf; fixes music continuing after system controls desynced the local session
Previous release: v1.0.0-beta.7
Unavailable releases
The following builds are not recommended due to a white-screen issue in packaged desktop apps:
- v1.0.0-beta.2 — Unavailable
- v1.0.0-beta.1 — Unavailable
Installation & Common Issues
SpinDeck desktop builds are not yet signed with Apple or Microsoft certificates. You may hit platform-specific issues when installing or opening the app for the first time.
All platforms
| Symptom | Cause | What to do |
|---|---|---|
| White screen or immediate quit | WebView / frontend assets failed to load | Relaunch; if it persists, check the log paths below |
Log locations (startup failures / crashes):
- macOS:
~/Library/Logs/com.spindeck.app/ - Windows:
%LOCALAPPDATA%\com.spindeck.app\logs\ - Linux:
~/.local/share/com.spindeck.app/logs/(may vary by distro)
Each launch creates a new session log named with the local timestamp, e.g. spindeck-2026-07-31_01-50-45.log. Multiple historical session files are kept (about 50 most recent). Logs include the Rust native layer (IPC / cover proxy / panic) plus critical frontend errors.
macOS
macOS applies the strictest restrictions to unsigned apps. Most “can’t open / can’t install” reports come from macOS.
| Symptom | Cause | What to do |
|---|---|---|
| “SpinDeck cannot be opened because Apple cannot check it for malicious software” | Gatekeeper blocking an unsigned app | Option A: Right-click (or Control-click) SpinDeck.app → Open → click Open again in the dialog.Option B: System Settings → Privacy & Security → find the blocked app notice → Open Anyway |
| “SpinDeck is damaged and can’t be opened. You should move it to the Trash” | Download quarantine attribute (com.apple.quarantine) | In Terminal (replace the path with your actual .app location):xattr -cr /Applications/SpinDeck.appThen right-click → Open again |
| Double-clicking inside the DMG does nothing useful | App was not copied to Applications | Drag SpinDeck.app into Applications, then launch from Launchpad or the Applications folder |
| Wrong architecture | Build does not match your Mac | Apple Silicon (M-series): use the macos-arm asset; Intel Macs: use macos-intel |
macOS Accessibility permission (pause/resume)
SpinDeck controls local music clients (QQ Music, NetEase, etc.) on macOS via AppleScript for pause/resume, which requires the Accessibility permission. Play-only (URL scheme) does not need it, but pause / resume must be authorized.
| Symptom | Cause | What to do |
|---|---|---|
| Clicking pause does nothing and the app prompts for Accessibility | SpinDeck lacks Accessibility permission | Open System Settings → Privacy & Security → Accessibility and toggle SpinDeck on |
| Toggle is on but the prompt still appears | TCC database did not refresh (occasional macOS issue) | Toggle off and back on; or remove SpinDeck with 「–」, restart the app, and re-authorize |
| Pause turns into play (clicking pause while nothing is playing) | Old versions' space-key fallback triggers play when idle | Upgrade to v1.0.0-beta.5 or later; the new build checks playback state before sending pause |
| Works in dev, fails in packaged build | The packaged .app has a different signing/permission context than dev | Re-grant Accessibility permission to the SpinDeck.app installed in /Applications |
Authorization steps:
- On first pause click, the app shows a prompt and opens System Settings → Privacy & Security → Accessibility
- Find SpinDeck in the list and toggle it on
- Return to the app and click pause again
Permission not taking effect?
If the toggle is on but the prompt still appears, try: System Settings → Privacy & Security → Accessibility → select SpinDeck → click 「–」 to remove → restart SpinDeck → authorize again when prompted. This is a known occasional issue with the macOS TCC database.
TIP
If the app still won’t open, do not run it directly from the mounted DMG. Copy it to Applications first, then follow the Gatekeeper steps above.
Windows
| Symptom | Cause | What to do |
|---|---|---|
| SmartScreen: “Windows protected your PC” | Installer is not EV-signed | Click More info → Run anyway |
| Blocked by antivirus | Unsigned desktop binary / WebView process | Add the SpinDeck install folder or .exe to your allowlist |
Linux
| Symptom | Cause | What to do |
|---|---|---|
| AppImage won’t run | Missing execute permission | chmod +x spindeck-*.AppImage, then run it |
| AppImage FUSE error | FUSE not installed | Ubuntu/Debian: sudo apt install libfuse2; or use the .deb package instead |
.deb missing dependencies | WebKit / graphics libraries | Install WebKit GTK and related packages (see build-from-source Linux deps) |
Build from Source
Full toolchain and OS matrix: System Requirements. Quick checklist below.
Additional Requirements
- Rust (stable)
- Platform toolchain (e.g. Xcode Command Line Tools on macOS)
Development
Tauri starts the web Vite server and loads it in the WebView. Desktop features use Tauri invoke:
pnpm --filter @spindeck/desktop devThis runs @spindeck/web and opens the SpinDeck window.
Production Build
pnpm --filter @spindeck/desktop buildBuilds the SPA into Tauri frontendDist, then runs tauri build. The packaged app loads the SPA via Tauri’s native asset protocol and uses invoke / cover:// for desktop features — no Node.js on the user’s machine.
Output is written to apps/desktop/src-tauri/target/release/bundle/ (.app on macOS, .msi / .exe on Windows, etc.).
Profile memory on release builds
Dev mode also runs Vite (http://localhost:5173) with uncompressed assets, so Activity Monitor numbers run high. Compare WebContent / Graphics using the production artifacts from this section.
Runtime notes (short)
- The installer is small; resident memory is dominated by the system WebView plus frontend 3D / compositing—not the Rust binary itself.
- By default SpinDeck keeps atmosphere effects (blurred backdrop, glass, vinyl glow, etc.) and controls peaks by unloading off-screen 3D resources rather than softening the visible frame. See Performance & Visuals.
Icons
Desktop icons are generated from apps/web/app/assets/icons/SpinDeckLogo.svg. Regenerate after logo changes:
pnpm desktop:icons
𝓒𝓱𝓮𝓻𝓻𝔂🍒