Settings & Files

Where things live

Spotifast was previously called Fastpotify. The existing fastpotify file paths, credential-store IDs and desktop integration IDs stay the same, so the rename does not require signing in again or moving your settings. Both spotifast and fastpotify commands control the same running app. Saved Spotify Connect device names remain unchanged; new settings default to Spotifast.

Spotifast follows each platform’s conventions. On Linux:

Clearing caches never signs you out. Sign-out from Settings covers the shared and personal Web API grants and the independent playback credential.

The following credential storage is on main, for the release after 0.7.1.

Durable grants use Secret Service on Linux, Keychain on macOS, and Credential Manager on Windows, under the service name rocks.fastpotify.Fastpotify. Entries are separated by application state location and grant type; Web grants carry their Client ID and must verify as the same account. Playback and receiver activation require that account too. Non-secret settings and session data remain readable JSON. Native credential protection reduces exposure from copying ordinary application files. It does not protect a usable session from arbitrary code running as the same user; Linux protection also depends on the desktop keyring’s configuration.

On Linux, enable and unlock a Secret Service provider such as GNOME Keyring or KWallet to remember a new sign-in. Flatpak is allowed to talk to org.freedesktop.secrets for this purpose. An unavailable or locked store produces an error without blocking the interface. A new sign-in can still be used for this session, with no new plaintext fallback file.

On upgrade, each legacy grant is written to the protected store and read back before its old file is removed. Valid grants migrate without signing in again. If Spotify rejects a saved refresh grant, only that grant is forgotten so the next launch cannot keep restoring it. If migration fails, Spotifast reports it and keeps the original so migration can be retried. That grant can still serve the current session. A successfully migrated grant is never replaced by a stale legacy copy. Librespot’s reusable grant stays in memory until Spotifast saves it through this same store. Volume and disposable audio caches are independent.

Sign-out invalidates pending authorization, refresh, and playback connections, and cancels pending Spotify requests so their results cannot undo a new sign-in. It records non-secret revocation markers before deleting the protected entries and all legacy token files, including temporary copies. A locked store or filesystem failure is reported. Revocation markers prevent a failed protected entry deletion from restoring the session on restart; keep these markers when a deletion failed. Removing or changing a personal Client ID clears that app’s old grant.

Version 0.7.1 and earlier use the legacy unencrypted files listed above. Their Web API writer requests owner-only permissions for newly created Unix files; Windows uses inherited permissions. Librespot’s old writer uses the system’s file defaults. Keep these legacy files, their temporary copies, the credentials/ directory, and credential-store exports out of issue attachments and diagnostic uploads.

Progress through a playlist is periodically cached as a contiguous prefix. When the playlist has not changed on Spotify, reopening it resumes from that prefix instead of requesting the same pages again. Spotifast validates the cache against Spotify’s playlist snapshot and reported song count before showing it. A cache with a mismatched count is replaced by live rows even if its snapshot matches, so stale cached songs cannot choose the playback order. Successful playlist edits keep that loaded prefix and save it under Spotify’s new snapshot after all pending writes have succeeded. Pending edits remain visible immediately, but are not saved as confirmed playlist rows. A failed write reloads the playlist to reconcile the edit.

On main, after 0.7.1, playlist checkpoints stream their JSON to a temporary file on a background file worker. Saving a large playlist no longer needs a second complete JSON buffer in memory. The cache format and checkpoint order are unchanged, and a failed write leaves the previous cache in place.

The following Liked Songs caching behavior is on main, for the release after 0.7.1.

Liked Songs metadata is stored separately under liked-songs/ in the cache directory, one JSON file per account. Only the verified account’s rows are shown. Fresh cached pages are reused for 15 minutes; older pages refresh in the background. Refreshing keeps the last usable rows until their replacement is ready, and a failed refresh leaves those rows visible. The refresh control requests current data immediately. Partial caches resume from their next page. Like and Unlike change the rows immediately, and confirmed edits survive a restart even if Spotify’s next read still reports the old state. This cache contains metadata, not offline audio, and can be deleted without signing out.

The last good playlist folder tree is kept in session.json, scoped to the account that supplied it. This keeps folders visible when local playback is temporarily unavailable. Live session data is still required for edit grants.

On main, for the release after 0.7.1, memory caches retain the open page, the playing context, and a limited set of recently used playlist, album, artist, and show pages. Older pages reload when revisited, using the saved playlist prefix when its snapshot still matches. Pending playlist edits and their rows stay in memory until the write and its snapshot are confirmed, even if this temporarily exceeds the usual page limit. Track metadata is limited to 800 cached tracks; navigation and periodic cleanup trim old entries.

The session remembers separate positions for the main window and the Winamp mini player. The shade modes are kept in settings.json. Wayland compositors may ignore saved positions. On Windows, a position whose title bar is no longer on an available monitor’s work area is discarded when reopening the window, keeping its initial on-screen placement instead.

On main, for the release after 0.7.1, a main window left maximized or full screen reopens that way, and comes back that way from the mini player. The remembered size and position describe an ordinary window and are not applied to one that already fills the screen, because sizing or moving such a window restores it down.

Large playlist pages also have a Go to song control. Entering a song number loads its 50-item page directly, without requesting every earlier page. Filtering or sorting still covers the whole playlist, so either action returns to the beginning and loads the remaining pages as needed.

On main, for the release after 0.7.1, Flatpak also preserves the fallback state directory used when XDG_STATE_HOME is unset. Session state, history, logs, and credential revocation markers survive a full quit and relaunch under ~/.var/app/rocks.fastpotify.Fastpotify/.local/state/fastpotify/. Configuration and caches remain under the app’s config/ and cache/ directories. State already lost on quitting an older release cannot be recovered.

On macOS, settings, state, and the logs are in ~/Library/Application Support/me.paolino.fastpotify and the caches in ~/Library/Caches/me.paolino.fastpotify. On Windows, settings are in %APPDATA%\paolino\fastpotify\config, state and the logs in %LOCALAPPDATA%\paolino\fastpotify\data, and the caches in %LOCALAPPDATA%\paolino\fastpotify\cache.

settings.json

Settings are stored in one readable JSON file and written atomically. Its main fields are:

Command line

spotifast [OPTIONS] [LINK]

  LINK                  A Spotify link to open: spotify:track:…, or an
                        open.spotify.com address
  --device-name <NAME>  Spotify Connect name for this session
  -v, --verbose         More logs from librespot and the API client

A link goes to the running Spotifast when there is one, which then opens the page and brings its window forward; otherwise the app starts on it. The desktop’s handler for spotify: links runs exactly this.

Attach fastpotify.log from the state directory to bug reports. It contains the last run’s output, including extra lines from spotifast -v. After a crash, attach panic.log too.

Demo mode

Builds made with cargo build --features demo accept --demo, which loads sample data for screenshots and interface work. Demo mode never writes settings.

--demo-page opens a page, such as home, playlist:pl1, or artist:art0, and --demo-show adds surfaces on top of it: a comma separated list of queue, playing-next, devices, shortcuts, premium, create, duplicate, light, focus, winamp, playlist, eq, eq-shade, compact, update, and personal-app. update shows a sample update badge for checking its layout. personal-app shows the personal Spotify app introduction.

--demo-shot <PATH> writes the window to a PNG and exits, which is useful for making deterministic screenshots for these pages:

cargo run --release --features demo -- \
  --demo-shot docs/screenshot.png --demo-page playlist:pl1 --demo-show queue

The image uses the current window size. --demo-size WIDTHxHEIGHT sets that size in logical pixels for a shot (for example 760x800 or 1240x800). --demo-shot-delay <MS> sets how long to wait for cover art before taking it. On main, after 0.7.1, demo windows ignore saved window geometry and do not read or save the normal window’s framework state. Existing appearance settings still apply. --demo-data <DIRECTORY> keeps demo caches and logs under that directory’s cache and state folders, with settings read from config.

Home shelves

On main, after 0.7.1, you can hide Made for you and Recommended for you from Home independently. Quit Spotifast before editing settings.json, then restart it. Add this field to hide both:

"home": {
  "made_for_you": { "visible": false },
  "recommendations": { "visible": false }
}

Set either visible value to true to show that shelf again. Omitted preferences keep both shelves visible. Other Home sections keep their normal order and contents. This changes what is displayed; hidden shelves still refresh in the background.