Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

The app keeps its settings in a TOML file, config.toml:

InstallLocation
Windows%APPDATA%\cider-offline\CiderOffline\config\config.toml
macOS~/Library/Application Support/sh.cider-offline.CiderOffline/config.toml
Linux~/.config/cideroffline/config.toml (or $XDG_CONFIG_HOME/cideroffline/config.toml)
Portabledata/config/config.toml next to the program

Most options are on the Settings page, and the app writes the file whenever you change one there. Without the file, every option has its default.

If you edit the file by hand, quit the app first, or it may overwrite your changes with its own copy. Missing keys take their default and unknown keys are ignored. If the file isn’t valid TOML, or holds a value the app can’t use (such as port = 0), the app logs invalid config; using defaults together with the reason and starts with the defaults. It leaves the broken file alone at startup, but the next change you make on the Settings page saves the defaults over it, so fix it first.

Top-level options

KeyTypeDefaultEffect
mode"active" or "passthrough""active"Mode the proxy starts in. passthrough forwards everything untouched.
captureboolfalseWrite Apple Music requests and responses to the captures folder.
auto_cache"off", "instant" or "deferred""off"Download songs as they play: never, right away, or once playback has been idle for 30 seconds.
detail_level"full" or "minimal""full"How much metadata is stored for each song. minimal keeps only id, title, artist, album, duration and artwork.
download_concurrencyinteger0Downloads that run at once, 1 to 6. 0 means the default, 2. Larger values are capped at 6.
overwrite_audioboolfalseReplace audio a song already has when downloading or importing, instead of skipping it.
overwrite_lyricsboolfalseWhen fetching lyrics for a collection or after a download, look up songs that already have lyrics again. Apple lyrics are always kept.
start_with_osboolfalseStart the app when you sign in.
start_minimizedboolfalseStart hidden in the tray (minimized when there is no tray).
cider_config_pathpathnot setCider’s client-options.yml, when you picked it with Choose config file… (Windows).
tray_hint_dismissedboolfalseThe one-time “no system tray” hint on Linux was dismissed.

[proxy]

KeyTypeDefaultEffect
bind_addressIP address"127.0.0.1"Address the proxy listens on. The default keeps it reachable from this computer only.
portinteger8000TCP port, 1 to 65535, the same range the Settings page accepts. 0 is not allowed, since Cider has to be pointed at a fixed address: a file with port = 0 counts as invalid (see above).

[connectivity]

The connectivity monitor decides whether Apple Music is reachable.

KeyTypeDefaultEffect
enabledbooltrueRun the monitor. When off, the proxy assumes it is online (a failed request still gets an offline answer).
probe_urlstring"https://amp-api.music.apple.com/"URL checked with a HEAD request. Any HTTP response counts as online.
interval_secsinteger15Seconds between checks (at least 1).
timeout_secsinteger5Timeout of one check in seconds (at least 1).
force_offlineboolfalseTreat Apple Music as unreachable, so every request is answered from your computer. Useful to see what works offline.

[library]

KeyTypeDefaultEffect
songs_page"apple" or "all""apple"What Cider’s Library > Songs page lists. apple: only the songs you added to your library, like Apple Music. all: every song of your library, including those in library playlists and albums.

[lyrics]

KeyTypeDefaultEffect
providersarray of { id, enabled }all seven, enabledLyrics providers in the order they are asked.
on_failure"skip_and_retry_later", "wait_and_retry" or "skip""skip_and_retry_later"What happens when a provider fails (rate limit, server error, timeout, network error).
policy_providersarray of provider idsall sevenProviders on_failure applies to. The others always wait and retry.
target_quality"word", "line" or "plain""word"Stop asking providers once lyrics this good are found; otherwise keep the best found.
fetch_after_downloadbooltrueLook up lyrics for each song once its download finishes.
lrclib_spacing_msinteger250Milliseconds between two LRCLIB lookups (at most 10000).
retry_passesinteger3Retry passes over skipped songs with skip_and_retry_later (1 to 10).
always_use_downloadedboolfalseWhile online, answer Cider’s lyrics requests with saved lyrics when a song has any, without asking Apple.

The provider ids, in the default order, are apple, community, amll, musixmatch, netease, kugou and lrclib. A provider missing from providers is added at the end, enabled.

wait_and_retry waits 2, 5, 15 and then 30 seconds between attempts, or as long as the provider’s Retry-After header asks. skip_and_retry_later waits longer before each pass (10 s, 30 s, 90 s and so on).

Example

mode = "active"
capture = false
auto_cache = "deferred"
detail_level = "full"
download_concurrency = 2
overwrite_audio = false
overwrite_lyrics = false
start_with_os = true
start_minimized = true
tray_hint_dismissed = false

[proxy]
bind_address = "127.0.0.1"
port = 8000

[connectivity]
enabled = true
probe_url = "https://amp-api.music.apple.com/"
interval_secs = 15
timeout_secs = 5
force_offline = false

[library]
songs_page = "apple"

[lyrics]
on_failure = "skip_and_retry_later"
policy_providers = ["apple", "community", "amll", "musixmatch", "netease", "kugou", "lrclib"]
target_quality = "word"
fetch_after_download = true
lrclib_spacing_ms = 250
retry_passes = 3
always_use_downloaded = false

[[lyrics.providers]]
id = "apple"
enabled = true

[[lyrics.providers]]
id = "lrclib"
enabled = true

[[lyrics.providers]]
id = "musixmatch"
enabled = false

In this example LRCLIB is asked right after Apple, Musixmatch is off, and the providers not listed (community, amll, netease, kugou) are added at the end, enabled.

Command-line options

OptionEffect
--versionPrint cider-offline <version> and exit.
--minimizedStart in the tray, like start_minimized. The login entry passes it.
--remove-all-dataUndo the system changes and delete the app’s files, then exit. See Uninstalling.
--uninstall-cleanupUndo the system changes only, then exit.
--dry-runWith one of the two above: print what would be done and change nothing.

On Windows the release build has no console window, so --version prints nothing you can see there. The app also has a few checks meant for development; they are listed in Development.

Logging is controlled with the RUST_LOG environment variable; see Troubleshooting.