Skip to content

Latest commit

 

History

History
22 lines (20 loc) · 8.46 KB

limitations.md

File metadata and controls

22 lines (20 loc) · 8.46 KB

Known limitations

Most entries below are about Spotify. Apple Music's own gaps are in Apple Music › Not there yet.

  • App Sandbox is disabled — The Wax macOS bundle ships with com.apple.security.app-sandbox set to false. Settings no longer need it: they live in ~/Library/Application Support/Spotiglass/settings.json (moved there from ~/.config/spotiglass/ on first launch), which a sandboxed build could keep in its container. Whether the rest of the app can run sandboxed is tracked in #387. The trade-off is that Wax can read and write outside its container, even though releases are Developer ID signed and notarized.
  • Spotify Premium for playback — The Web Playback SDK reports account_error for non-Premium accounts. Wax shows a clear “Spotify Premium required” style message. Playlist browsing may still work without Premium.
  • Play/pause — The transport bar and track-row toggle use the Web Playback SDK (player.togglePlay in the hidden web view), not PUT /v1/me/player/pause. The app serializes rapid toggles until the bridge confirms the SDK command (or a short timeout). The default Space shortcut for play/pause runs only when playback is in a transport-ready state (connecting / signed-out still typable elsewhere). The REST pause implementation still avoids a redundant PUT when GET /v1/me/player shows the same active device and is_playing is already false (and it coalesces concurrent pause calls).
  • Playback bar volume — The slider adjusts Spotify Web Playback SDK output (player.setVolume) inside Spotiglass. It is not the macOS system output volume; menu bar / Control Center still control overall device level.
  • Playback device menu — The playback bar menu lists Spotify Connect devices first (GET /v1/me/player/devices + transfer), then a separator, then Mac audio outputs from Core Audio (same devices Control Center shows). Choosing a Connect row moves Spotify playback only. Choosing a Mac row sets the system default output device (system-wide), which is where Web Playback audio goes when this Mac is the active player. The circular icon uses hybrid SF Symbols: when the active Spotify device is this app’s Web Playback device, the icon follows the default macOS output name (Core Audio); otherwise it follows the active Connect device name from Spotify. Single-ear AirPods icons (airpods.left / airpods.right) are best-effort only when the OS-reported device name suggests one side; Spotify’s API does not expose single-bud state.
  • Playback connects when signed in — After successful Spotify sign-in, Wax registers the hidden Web Playback SDK device automatically. Use Reconnect in the playback bar (or the Command Palette “Connect Playback” command) only when playback drops or errors.
  • Signed releases, unsigned previews — Releases on GitHub since 0.5.0, and the updates Sparkle installs, are Developer ID signed, notarized and stapled, so Gatekeeper opens them like any other app (see CI and releases). The short-lived Release artifact from CI and local make release builds are not: Gatekeeper may block them, and the equalizer only installs in a notarized build. Don't hand those builds out as releases.
  • Apple Music subscription for playback — Without one, the Apple Music library still loads, and the transport bar says playing needs a subscription.
  • No backend — All Spotify and Apple Music traffic goes directly from the Mac client (Apple Music through MusicKit and the Apple Music API). No Wax server, telemetry product, or cross-machine sync.
  • Single Spotify session — One signed-in account at a time. To switch accounts: Disconnect (clears Keychain refresh token and local cache), then Connect again.
  • Fixed OAuth loopback port — Sign-in listens on 127.0.0.1:43824. Another process binding that port during sign-in prevents the listener from starting; resolve the conflict and retry.
  • Playlist items API limit — Spotify’s playlist tracks endpoint returns at most 50 items per request. Wax paginates and merges pages; users still see full playlists, but network traffic is chunked accordingly.
  • Liked Songs load cap — GET /v1/me/tracks is paginated the same way, but Wax stops after 20 pages of 50 (at most 1,000 liked tracks loaded into the UI) so very large libraries do not issue unbounded requests. Spotify’s total count still appears in the header when the API reports it; only the loaded slice is playable from this list.
  • Shuffle and repeat — Controlled via Spotify Web API (PUT shuffle/repeat, GET player for state). They apply to Spotify’s active playback device; Wax sends your Web Playback device id when you use the in-app controls. While Repeat one is on, Up next is empty in Wax because Spotify’s queue and Web Playback still expose the contextual track order even though playback loops the current track. Queue order after shuffle comes from Spotify’s queue response on refresh.
  • Artist pages — Artist detail and discography come from Spotify Web API endpoints (/v1/artists/...). In Development mode, Spotify may forbid GET /v1/artists/{id}/top-tracks (see Feb 2026 Web API dev-mode changes); Wax then fills the Tracks row from artist-scoped search and, if both fail, recent album/single tracks. The album fallback issues one batched GET /v1/albums?ids=... request (Spotify caps that endpoint at 20 IDs per call) covering up to 6 albums (3 under rate-limit pressure), each returning its first track page inline. At most one single-album GET /v1/albums/{id}/tracks recovery call is made if the batched response was missing tracks for an album we still need; if the top-tracks probe hit HTTP 429 with a long Retry-After, the album fallback is skipped entirely so we don't stack another outbound call onto the active back-off window. GET /v1/artists/{id}/albums accepts at most limit=10 per request (reference); Wax uses that page size and follows next, but stops after 20 pages (at most ~200 albums) so large discographies do not trigger long bursts of requests or HTTP 429. The artist view requests album, single, and compilation groups only (not appears_on), which further reduces page count. Requests use your profile country as market when Spotify provides it.
  • Queue panel sync — The in-app Queue panel shows “now playing” from live Web Playback state, upcoming tracks from the Web API’s GET /v1/me/player/queue, and uses ~4s polling while the panel is open (Spotify does not push queue changes over the Web API). Changes made in other Spotify clients may lag briefly. Remove / reorder in queue is not supported — those controls are not exposed by the Web API for third-party apps.
  • Web API rate limits — Spotify may return HTTP 429 with Retry-After if usage is very high. Wax debounces palette search (global Spotify search does not run until the palette query is at least two non-whitespace characters), caches eligible GET responses in memory and on disk (with normalized cache keys for /v1/search), skips redundant identical palette searches, backs off palette dispatch briefly after a 429, and skips extra artist-scoped track search when the primary result set is already full; very heavy use can still hit Spotify’s limits.
  • In-app lyrics (LRCLIB) — Synced lyrics come from the third-party LRCLIB HTTP API, not from Spotify. For each resolution, Wax requests get-cached and get in parallel (then prefers a usable get-cached body, else get) to reduce wait time. Coverage is community-driven: many tracks have timed lines, some only plain text, and some return nothing. Timing accuracy can vary. The API is documented as beta and may change. Lyrics require network access from your Mac; Wax sends a User-Agent identifying the app. This feature is unrelated to Spotify’s own lyrics licensing or catalog guarantees. While a music track is actively playing (not while paused), Wax prefetches LRCLIB results in the background and caches successful fetches on disk for faster repeat playback; the first time on a new track (or after a failed prefetch) you may still see a brief fetch.