v1.0.0-beta.4

SpinDeck v1.0.0-beta.4

Desktop-focused beta with macOS playback fixes and a more reliable shelf experience.

Highlights

• macOS QQ Music control — Fixed AppleScript pause/resume scripts; space-bar fallback when menu automation fails; leaving the shelf no longer toggles already-paused playback back on
• Pre-launch & external links — Pre-launch opens QQ Music, NetEase Music, and Kugou via Tauri shell.open; settings and playlist URLs open in the system browser instead of the in-app WebView
• Playlist refresh — Manual refresh bypasses the QQ Music in-memory cache and re-fetches from the API; the 3D vinyl shelf rebuilds when song data changes
• Desktop runtime — Tauri dev resources, WebView remote permissions, shell URL allowlist, and Vite SSR compatibility fixes for local development

Requirements

Release builds still require Node.js 20+ on your machine to run the embedded local server.

Downloads

Pick the asset for your platform (macOS arm/intel .dmg, Windows .msi / .exe, Linux AppImage / .deb, etc.).

Previous releases

• v1.0.0-beta.3 — earlier desktop beta (still usable)
• v1.0.0-beta.1 / beta.2 — not recommended (white-screen issue in packaged builds)

v1.0.0-beta.3

SpinDeck v1.0.0-beta.3

First usable desktop pre-release. Fixes the post-install white screen and startup timeout issues present in beta.1 and beta.2.

Fixes

• Desktop startup failure — Fixed embedded Node server failing to start, which caused “Timed out waiting for port 17345”
• Missing runtime dependencies — Fixed nested packages (e.g. Express → body-parser) not being bundled after pnpm deploy
• White screen / SSR — Fixed React dual-instance conflict in the desktop runtime
• Startup crash — Server startup failures no longer panic the app; an error page is shown and details are written to logs
• macOS Node resolution — Improved detection of node from Homebrew, nvm, and other common installs

Requirements

• Node.js 20+ (the desktop app runs an embedded server using your system Node; Node is not bundled yet)
• macOS 12+ / Windows 10+ / mainstream Linux distributions

Installation (macOS)

1. Download the .dmg for your architecture (aarch64 for Apple Silicon, x64 for Intel)
2. Open the DMG and drag SpinDeck.app into Applications — do not run it directly from the mounted volume
3. If Gatekeeper blocks the app: right-click → Open → confirm Open again
4. If macOS reports the app as “damaged”: run xattr -cr /Applications/SpinDeck.app
5. Ensure Node.js is installed: node -v (must be ≥ 20)

Troubleshooting

Log directory:

• macOS: ~/Library/Logs/com.spindeck.app/
• Windows: %LOCALAPPDATA%\com.spindeck.app\logs\
• Linux: ~/.local/share/com.spindeck.app/logs/

Do not use

These releases have known white-screen issues:

• v1.0.0-beta.1
• v1.0.0-beta.2

Docs

• Desktop app guide

---

Full desktop player control is currently recommended on macOS only (Windows/Linux playback control remains limited).

v1.0.0-beta.2

Release Notes — Playlist Import & On-Demand Loading

Overview

This release improves how SpinDeck imports and displays playlists from QQ Music, Kugou, and NetEase Cloud Music. Large playlists load faster and more reliably, with platform-specific strategies: full load where APIs allow it, and pagination where they do not.

---

✨ New Features

On-demand playlist loading

• NetEase Cloud Music playlists now load in pages (30 songs per request) instead of fetching the entire list upfront.
• The 3D shelf renders the full playlist length immediately using placeholders, while songs and covers load incrementally as you scroll.
• Scroll-based preloading fetches upcoming songs before you reach them.

Unified playlist page API (getPlaylistPage)

• New core API with consistent response shape: songs, offset, limit, hasMore, paginated, platformPlaylistId.
• isPaginatedPlaylistPlatform() identifies platforms that require pagination (NetEase only).

Metadata-only refresh

• Playlists can be refreshed with metaOnly: true to update title, cover, and song count without reloading already-fetched songs.
• Background refresh and create-playlist flows use this to avoid unnecessary full re-imports.

---

🚀 Improvements

QQ Music & Kugou — full load restored

• These platforms load the full playlist in a single request (up to 300 songs), matching the original fast behavior.
• Raw response caching reduces repeated parsing overhead for QQ Music.

NetEase Cloud Music — stability & rate limiting

• Primary path now uses the v6 playlist detail API (/api/v6/playlist/detail) with 60-second page caching.
• Avoids the legacy v1 API that triggered 405 (“too frequent”) errors under repeated requests.
• When v6 track data is incomplete, falls back to trackIds + /api/song/detail instead of v1.
• v1 is only used as a last resort when v6 fully fails.
• User-friendly error message when rate-limited: “网易云请求过于频繁，请稍后再试”.

Album cover fixes (NetEase)

• Fixed missing album art on the 3D shelf for NetEase songs.
• /api/song/detail returns album.picUrl and artists (not al / ar like v6); parser now supports both formats.
• Cover URLs are normalized to HTTPS.
• When merging v6 and song/detail data, v6 cover art is preserved as a fallback.

Image proxy

• /api/image now selects the correct Referer header based on CDN domain:
  • NetEase (126.net, 163.com) → https://music.163.com/
  • QQ Music → https://y.qq.com/

3D shelf (PlaylistShelf)

• Accepts totalSongCount for paginated playlists (shelf length independent of loaded songs).
• onScrollCenter callback triggers loading as the user scrolls.
• Incremental spine and cover updates when new song pages arrive.
• Placeholder books shown for not-yet-loaded tracks.

---

🔧 API Changes

POST /api/import

• New form fields: offset, limit, metaOnly, platformPlaylistId.
• Response includes: paginated, hasMore, songCount, platformPlaylistId.
• QQ / Kugou: single full-load response (paginated: false).
• NetEase: paginated response (paginated: true).

---

📦 Changed Files (summary)

Area	Files
Core	getPlaylistPage.ts, getNeteaseMusicList.ts, getQQMusicList.ts, getKugouMusicList.ts, playlistCache.ts
Web API	api.import.ts, api.image.ts
UI	PlaylistShelf.tsx, use-playlist-fetch.ts, shelf.$playlistId.tsx, CreatePlaylistModal.tsx, use-background-refresh.ts

---

🧪 Testing Checklist

• Import a large NetEase playlist — songs load page by page; shelf scrolls smoothly
• NetEase album covers appear on book spines and in playback view
• Import a QQ Music playlist — full list loads in one request; speed comparable to before
• Import a Kugou playlist — same full-load behavior
• Scroll deep into a NetEase playlist — additional pages load without 405 errors
• Background metadata refresh updates title/cover without clearing loaded songs

---

⚠️ Known Notes

• NetEase remains the only paginated platform; QQ and Kugou are capped at 300 songs per import.
• ESLint warnings on PlaylistShelf useEffect dependencies are intentional — rebuilding the full 3D scene on every page load would hurt performance.

v1.0.0-beta.1

First release