Settings & Files

Where things live

Linux media controls use playerctl --player=tidalfast.

Tidalfast follows each platform’s conventions. On Linux:

Clearing caches never signs you out. Sign-out from Settings removes the stored TIDAL grant and the cached library of every account: playlist pages, the playlist list, Home shelves and My Collection tracks metadata. The audio, artwork and lyrics caches stay, since they belong to no account.

Credential storage

The durable TIDAL grant (access and refresh token, plus the sign-in flow that minted it) uses Secret Service on Linux, Keychain on macOS, and Credential Manager on Windows, under the service name rocks.tidalfast.Tidalfast. 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 plaintext fallback file.

Sign-out invalidates pending authorization and refresh requests so their results cannot undo a new sign-in. It records non-secret revocation markers before deleting the protected entries. 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.

Proxy passwords use a separate protected entry under the same service name. They belong to the configured host, port, and username. Editing any of these fields clears the old password; changing only HTTP/SOCKS5 mode keeps it. Off, System, and TIDAL sign-out retain the saved manual proxy password. Clear the password and apply the manual settings to forget it. Settings store the confirmed proxy mode, host, port, and username, never an unapplied draft or password.

The TIDAL OAuth client id and secret are not part of the app: they come from settings.json (tidal_client_id, tidal_client_secret, tidal_pkce_client_id). Keep that file out of issue attachments. How Tidalfast Talks to TIDAL describes the sign-in flows.

Library caches

Playlist pages are cached as a contiguous prefix, validated before display so a stale cache cannot choose the playback order. Reopening an unchanged playlist resumes from that prefix instead of requesting the same pages again. Pending edits show immediately and are saved as confirmed rows only after the write succeeds; a failed write reloads the playlist.

My Collection tracks metadata is stored under liked-songs/, one JSON file per account. Only the verified account’s rows are shown. Refreshing keeps the last usable rows until their replacement is ready, and a failed refresh leaves those rows visible. This cache contains metadata, not offline audio.

The playlist list (library/) and the Home shelves (home/) are stored the same way, one file per account. They are shown as soon as the account is verified and replaced as TIDAL answers; a failed read keeps what was shown. These caches contain metadata only and can be deleted at any time. Signing out deletes them.

Memory caches retain the open page, the playing context, and a limited set of recently used pages. Track metadata is limited to 800 cached tracks; navigation and periodic cleanup trim old entries.

The session remembers separate position for the main window, and its size and whether it was maximized. Sizes and positions are in logical pixels, so they do not change with the interface zoom. Wayland compositors may ignore saved positions. A window that opens on no connected monitor moves to the middle of the primary one on Windows and X11; on macOS, a position whose title bar would be on no screen is not used. A main window left maximized or full screen reopens that way. The shade modes are kept in settings.json.

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.tidalfast.Tidalfast/.local/state/tidalfast/. Configuration and caches remain under the app’s config/ and cache/ directories.

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

The running copy keeps its single-instance files in a private directory: $XDG_RUNTIME_DIR/tidalfast on Linux (inside Flatpak, the app’s own runtime directory), a tidalfast folder in your private temporary directory ($TMPDIR) on macOS, and an instance folder in the state directory on Windows. instance.lock marks the running copy; the system releases it when Tidalfast quits or crashes. instance.sock (Linux and macOS) is the socket a second launch and the tidalfast command reach it through, which only your user can open. On Windows, instance.key holds the loopback port and a random token that every request must carry. Tidalfast writes them on each start; nothing in them needs keeping.

settings.json

Settings are stored in one readable JSON file and written atomically. Its main fields are. Settings files from older versions still load; keys for features that were removed (the Winamp mini player, skins, visualisers and MilkDrop) are ignored.

Command line

tidalfast [OPTIONS] [LINK]
tidalfast <play-pause|play|pause|next|previous|seek|seek-to|volume|volume-up|...>

  LINK                  A TIDAL link to open: tidal:track:…, or a tidal.com
                        address
  --device-name <NAME>  The name this player goes by for this session
  --profile <NAME>      Use a separate profile (also TIDALFAST_PROFILE=<NAME>)
  --minimized           Open the window minimized (what "Launch at login" with
                        "Start minimized" runs)
  -v, --verbose         More logs from the TIDAL client

A separate profile (--profile test, or TIDALFAST_PROFILE=test; 1 to 32 letters, digits, - or _) keeps its own settings, state and cache in tidalfast-<name> folders beside the normal ones, its own sign-in under the credential-store service rocks.tidalfast.Tidalfast.profile.<name>, and its own single-instance slot, so it runs beside the normal Tidalfast and can never read, replace or sign out of the normal profile’s session. Links and control commands sent with the same profile reach that profile’s window.

A link or a control command goes to the running Tidalfast when there is one, which then opens the page and brings its window forward; otherwise the app starts on it. Run tidalfast --help for the full command list.

Attach tidalfast.log from the state directory to bug reports. It contains the last run’s output, including extra lines from tidalfast -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, shortcuts, create, light, focus, update, collection-loading, shuffle-selected, shuffle-started, lyrics, lyrics-fullscreen, signed-out, connecting, library-list, library-list-narrow, library-list-wide, library-grid, library-grid-narrow, library-grid-wide, and others listed by --help. The Library variants show the list or cover grid with a normal, narrow, or wide sidebar for matching captures. shuffle-selected and shuffle-started capture the selected-mode and playback-started outcomes of a collection Shuffle click. update shows a sample update badge. signed-out and connecting show the sign-in card before and while the session connects. collection-loading keeps known collection metadata and placeholder artwork visible while replacing the page content, with unfinished controls disabled. --demo-language <TAG> shows the interface in one of the bundled languages, such as es or ja, in place of the saved setting and the system’s language.

--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 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. --demo-drag X,Y:X,Y shows a drag in progress: the pointer presses at the first point, in logical pixels, and is still held down at the second when the shot is taken. --demo-dump-looks <PATH> (with --demo-shot) also writes, when the shot is taken, every Luna anchor of the window as JSON: its key, tag and attributes, the theme cascade’s style for it, and its resolved anchor look (colours as [r, g, b, a], lengths in points). It is for comparing a theme in Tidalfast with the same theme on TIDAL’s page in a browser, element by element. Since 0.8.0, demo windows ignore saved window geometry and do not read or save the normal window’s framework state. Existing built-in 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

You can hide the Made for you and Recommended for you shelves from Home independently. Quit Tidalfast 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. This changes what is displayed; hidden shelves still refresh in the background.