Skip to content

desktop.md

Latest commit

 

History

History
145 lines (98 loc) · 7.65 KB

desktop.md

File metadata and controls

145 lines (98 loc) · 7.65 KB
Raw
title Desktop App
weight 20

Desktop App

SpinDeck ships a Tauri 2 desktop shell for macOS, Windows, and Linux. The desktop build bundles the web UI and is recommended on macOS for full playback control.

Download

Download pre-built desktop installers from GitHub Releases:

v1.0.0-beta.5 (latest)

Pick the asset for your platform (.dmg / .app on macOS, .msi / .exe on Windows, etc.). Release builds currently require Node.js on the user's machine to run the embedded server.

What's new in v1.0.0-beta.5

  • macOS Accessibility permission — Pause/resume controls local clients via AppleScript and requires the Accessibility permission; the app auto-opens System Settings to guide authorization when missing
  • macOS QQ Music control — Fixed AppleScript pause/resume; keyboard fallback when menu control fails; idempotent pause avoids accidental resume when leaving the shelf; pause no longer triggers play when nothing is playing
  • Pre-launch & external links — Pre-launch opens local clients via Tauri shell.open; settings and playlist links open in the system browser
  • Playlist refresh — Manual refresh bypasses QQ Music server cache; 3D shelf rebuilds when song data changes
  • Desktop dev & runtime — Tauri dev resources, WebView capabilities, and Vite SSR compatibility fixes

Previous release: v1.0.0-beta.4

::: warning Unavailable releases The following builds are not recommended due to a white-screen issue in packaged desktop apps:

Installation & Common Issues

SpinDeck desktop builds are not yet signed with Apple or Microsoft certificates, and they require Node.js on your machine to run the embedded local server. 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 Node.js missing, or embedded server failed to start Install Node.js 20+ and relaunch; if it persists, check the log paths below
node not found GUI apps on some systems have a minimal PATH Ensure Node is installed; on macOS, Homebrew is recommended (see below)

Log locations (when startup fails):

  • macOS: ~/Library/Logs/com.spindeck.app/
  • Windows: %LOCALAPPDATA%\com.spindeck.app\logs\
  • Linux: ~/.local/share/com.spindeck.app/logs/ (may vary by distro)

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.app
Then 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:

  1. On first pause click, the app shows a prompt and opens System Settings → Privacy & Security → Accessibility
  2. Find SpinDeck in the list and toggle it on
  3. Return to the app and click pause again

::: tip 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. :::

Recommended Node.js install (macOS):

# Homebrew
brew install node

Verify with node -v (20 or newer).

::: 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
App won’t start after install Node.js not installed Install LTS from nodejs.org; enable Add to PATH during setup, then restart SpinDeck
Blocked by antivirus The app spawns a local Node.js server 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)
White screen after launch Node.js not installed Install Node.js 20+ via your package manager or nvm

Build from Source

Additional Requirements

  • Rust (stable)
  • Platform toolchain (e.g. Xcode Command Line Tools on macOS)

Development

Tauri loads the web dev server during development:

pnpm --filter @spindeck/desktop dev

This runs @spindeck/web dev and opens the SpinDeck window.

Production Build

pnpm --filter @spindeck/desktop build

Output is written to apps/desktop/src-tauri/target/release/bundle/ (.app on macOS, .msi / .exe on Windows, etc.).

Icons

Desktop icons are generated from apps/web/app/assets/icons/SpinDeckLogo.svg. Regenerate after logo changes:

pnpm desktop:icons