Cider Offline
Cider Offline is a desktop app for people who listen to Apple Music in Cider and want it to keep working without an internet connection. It runs a small proxy on your computer. Cider sends its Apple Music traffic through that proxy, the proxy keeps a local copy of your library, and when Apple Music can’t be reached it answers Cider from that copy instead.
It runs on Windows (x64, x86 and ARM64), macOS (one universal build for Intel and Apple silicon) and Linux (x86_64 and ARM64).
What it does
- Offline mode: when Apple Music is unreachable, Cider still shows your library, searches it and plays the songs you have downloaded.
- Library sync: your playlists, albums and Songs tab are fetched from Apple Music in full and kept up to date while you are online.
- Downloads: songs (and the audio of music videos) are downloaded and decrypted on your computer, so they play offline. Songs can also be downloaded automatically as you play them.
- Lyrics from Apple Music, Cider Community, AMLL TTML DB, Musixmatch, NetEase Cloud Music, Kugou and LRCLIB, saved locally and served to Cider offline.
- Your own audio and lyrics: give a song your own audio file or lyrics file (TTML or LRC), or add songs, albums and playlists of your own that show up in Cider’s library.
- One switch to point Cider at the proxy on Windows. On macOS and Linux the app shows the command to use.
- Start at login, start minimized, a system tray icon, and a portable build that keeps everything in one folder.
What you need
- Cider 4, the current release from the Cider Collective.
- An Apple Music subscription, signed in to Cider.
- Windows 10 or 11, macOS 11 or newer, or a Linux desktop with X11 or Wayland. On Linux the app needs
certutilfrom the NSS tools; the packages pull it in.
Where to start
- Install the app and trust its local certificate.
- Connect Cider to the proxy.
- Use Cider online once so the app can pick up your Apple Music session and sync your library. Then download what you want to have offline. Using the app covers the details.
If something doesn’t work, see Troubleshooting. To get rid of the app and everything it set up, see Uninstalling.
A note on use
Cider Offline is for personal use with your own Apple Music subscription. It is not affiliated with or endorsed by Apple or the Cider Collective. It decrypts content you are already licensed to stream so you can play it offline on your own machine. Use it at your own risk.
The app is open source under the MIT license. The code is at github.com/semicolonmystery/cider-offline.
Installation
Every release on the Releases page has an installer and a portable archive for each system, plus a SHA256SUMS.txt with the checksum of every file.
Use the installer unless you have a reason not to. The portable build is for running the app from a folder of your choice (a USB stick, a synced folder) with all of its data next to it. The two behave the same once they are running. See Files and folders for where each keeps its data.
Windows
| File | What it is |
|---|---|
cider-offline_<version>_x64-setup.exe | Installer for 64-bit Intel and AMD PCs |
cider-offline_<version>_x86-setup.exe | Installer for 32-bit Windows |
cider-offline_<version>_arm64-setup.exe | Installer for ARM64 PCs |
cider-offline_<version>_<arch>-portable.zip | Portable build for the same three architectures |
The installer installs for your user only, into %LOCALAPPDATA%\Cider Offline, and doesn’t ask for administrator rights. Installing a newer version over an older one keeps your data and settings.
For the portable build, unzip the archive anywhere you can write to. You get cider-offline.exe, a README.txt and an empty data folder. Keep the data folder next to the exe: that folder is what makes the app run in portable mode.
SmartScreen warning
The builds are not code-signed, so the first time you run the installer or the portable exe, Windows may show “Windows protected your PC”. Click More info, check that the app name is right, then click Run anyway.
macOS
| File | What it is |
|---|---|
cider-offline_<version>_universal.dmg | Disk image with the app, for Intel and Apple silicon Macs |
cider-offline_<version>_universal-portable.zip | Portable build: the app next to an empty data folder |
Open the .dmg and drag Cider Offline into Applications. macOS 11 or newer is required.
The app lives in the menu bar. It shows a Dock icon only while its window is open.
Gatekeeper warning
The macOS builds are not notarized by Apple (they are ad-hoc signed), so the first launch is blocked with a message that Apple could not check the app. To open it anyway:
- Try to open the app once and dismiss the message.
- Open System Settings > Privacy & Security, scroll down to the message about Cider Offline and click Open Anyway.
You can also remove the quarantine flag in Terminal:
xattr -dr com.apple.quarantine "/Applications/Cider Offline.app"
Portable build on macOS
macOS runs a quarantined app that came from a downloaded zip from a hidden, read-only copy (App Translocation). From there the app can’t see the data folder next to it and falls back to your normal user folders. The Overview page shows a warning when this happens. Before the first start, remove the quarantine from the unzipped folder:
xattr -dr com.apple.quarantine "/path/to/unzipped folder"
Linux
Builds exist for x86_64 and ARM64 (aarch64).
| File | What it is |
|---|---|
.deb | Package for Debian, Ubuntu and their derivatives |
.rpm | Package for Fedora, openSUSE and other rpm-based distributions |
cider-offline_<version>_<arch>.tar.gz and cider-offline_<version>_<arch>.PKGBUILD | Package for Arch Linux and its derivatives |
.AppImage | Single file that runs on most distributions |
cider-offline_<version>_<arch>-portable.tar.gz | Portable build: the AppImage next to an empty data folder |
Install the .deb or .rpm with your package manager, for example:
sudo apt install ./cider-offline_<version>_amd64.deb
sudo dnf install ./cider-offline-<version>.x86_64.rpm
The exact file names depend on the architecture; use the ones you downloaded.
For Arch, download the .tar.gz and the .PKGBUILD into the same folder, rename the .PKGBUILD file to PKGBUILD and run makepkg -si there.
The packages pull in what the app needs at runtime: the NSS tools (certutil), polkit (pkexec), xdg-utils and the usual graphics, font and keyboard libraries. For the AppImage, install certutil yourself: libnss3-tools on Debian and Ubuntu, nss-tools on Fedora, nss on Arch.
Make the AppImage executable before you run it:
chmod +x cider-offline_<version>_<arch>.AppImage
To use the system tray on GNOME, install the “AppIndicator and KStatusNotifierItem Support” extension. Without a tray the app still works, but closing its window quits it.
First run and the local certificate
When the app starts for the first time, the Overview page shows two steps: trust the local certificate, then connect Cider. Connecting Cider has its own page. This section is about the certificate.
Why it’s needed
Cider talks to Apple Music over HTTPS. To keep a copy of your library and answer Cider while you are offline, the proxy has to read those connections, and Cider only accepts that if the proxy can present a certificate it trusts. So on the first start the app creates its own certificate authority, called Cider Offline CA, on your computer. It is valid for about ten years. The certificate and its private key stay in the ca folder of the app’s data folder; on macOS and Linux the key file is readable only by you.
Click Install on the Certificate row of the Overview page. Your system then asks you to confirm:
- Windows adds the certificate to your user’s Root store and shows its own security warning. No administrator rights are needed.
- macOS adds it to your login keychain and asks for your password to change the trust settings.
- Linux adds it to your NSS database (
~/.pki/nssdb, plus the databases of a Flatpak or Snap Cider). That is the store Cider uses, and it needs no password. The app then also tries to add it to the system’s trust anchors, which asks for your password through polkit. That part is optional: if it is skipped, the row says the certificate is trusted for Cider and system-wide trust was not installed.
Check again re-reads the trust store, for example after you installed Cider as a Flatpak later. When the app can’t read the trust store, the row shows the reason and the button says Fix instead of Install; it runs the same installation again.
What the proxy can see
The proxy listens on 127.0.0.1 (your own computer only) on port 8000 by default. Only programs you point at it use it, which normally means just Cider.
In Active mode it decrypts and reads Cider’s traffic to Apple Music: hosts under music.apple.com, itunes.apple.com and mzstatic.com (artwork), and while offline also blobstore.apple.com (custom playlist covers). This is where it caches responses, captures the Apple Music session tokens it needs for syncing and downloading, and serves your local files. Connections to any other host pass through as encrypted tunnels that the proxy does not open. In Passthrough mode nothing is decrypted at all.
A trusted root certificate comes with a risk: whoever has its private key could make your computer accept a fake certificate for any website. The key is created on your computer and never leaves it. If you stop using the app, remove the certificate with Settings > Uninstall certificate, or use Remove all data, which also removes it (see Uninstalling).
Connecting Cider
Cider has to send its traffic through the proxy, and it has to trust the proxy’s certificate. The certificate is covered in Installation. This page covers the proxy setting.
The examples use the default address, 127.0.0.1:8000. If you changed the port, the Overview page shows your address, and the commands it shows already include it.
Windows
The Windows build of Cider has its own proxy setting, and the app can turn it on for you. On the Overview page, turn on Route Cider through this proxy.
Behind the switch, the app edits Cider’s settings file, %APPDATA%\sh.cider.dotnet\client-options.yml:
UseProxy: true
ProxyServer: 127.0.0.1:8000
Cider reads this file only when it starts and rewrites it when it exits, so the app makes the change while Cider is closed:
- If Cider is running, the app asks it to close, writes the file and starts Cider again. If Cider hasn’t closed after 10 seconds, the app ends it.
- If Cider isn’t running, the app writes the file and leaves Cider closed. The change applies the next time you start it.
Turning the switch off sets UseProxy: false and leaves ProxyServer as it is. The app changes only those two lines and leaves the rest of the file exactly as Cider wrote it.
If Cider keeps its settings somewhere else, the row says the file was not found. Click Choose config file… and pick Cider’s client-options.yml. The app remembers the choice (cider_config_path in the config), and the row shows which file it uses.
You can also make the change by hand: close Cider, set UseProxy: true and ProxyServer: 127.0.0.1:8000 in client-options.yml, and start Cider again.
macOS and Linux
Cider on macOS and Linux is a different build, and it has no proxy setting the app could change. Instead you start Cider with Chromium’s --proxy-server option, and the app never touches Cider’s files there. The Overview page shows the exact command under Use Cider with this proxy.
On macOS, quit Cider and start it from Terminal:
open -a Cider --args --proxy-server=127.0.0.1:8000
On Linux, quit Cider and start it with:
cider --proxy-server=127.0.0.1:8000
or, for the Flatpak:
flatpak run sh.cider.Cider --proxy-server=127.0.0.1:8000
The option applies only to the Cider you start this way. If you start Cider from the Dock, the app menu or a launcher, it runs without the proxy. To make it permanent, change your launcher or desktop entry to pass the option.
Instead of the option you can set a proxy for the whole system: on macOS in System Settings > Network > (your network) > Details > Proxies, on Linux in your desktop’s network settings. Set both the HTTP and the HTTPS proxy to 127.0.0.1 port 8000. This sends every app that follows the system proxy through Cider Offline. Apart from Apple Music hosts, the traffic passes through untouched, but it all stops working while the app isn’t running.
Checking that it works
With Cider running, the Requests seen counter on the Overview page goes up as you use Cider. If it stays at 0, Cider isn’t using the proxy. If Cider shows network errors as soon as it goes through the proxy, the certificate isn’t trusted yet. Troubleshooting has more on both.
Using the app
The window has three pages: Overview, Library and Settings. Closing the window doesn’t stop the proxy; the app keeps running in the system tray.
Overview
The large switch at the top picks the mode:
- Active (the default): Apple Music traffic is read, cached and, when Apple Music is unreachable, answered from your computer.
- Passthrough: every connection is forwarded untouched. Nothing is decrypted or cached, and offline mode does nothing.
Below it you see whether the proxy is online or offline, its address (with a Copy button), how many requests it has seen and how many it answered itself, the certificate and Cider rows from setup, and a short activity list.
Capture Apple traffic to disk writes every Apple Music request and response to the capture folder as JSON. It is meant for troubleshooting. The authorization, cookie and Apple Music user token headers are replaced with <redacted>, but the bodies are stored as they are, so look through the files before you share them.
Offline mode
While you are online, the proxy checks every 15 seconds whether Apple Music answers (a HEAD request to https://amp-api.music.apple.com/; any HTTP answer counts as online). When the check fails, or a request to Apple fails, the proxy switches to offline mode and answers Cider itself:
- your library playlists, albums and songs, in the same order as in Apple Music;
- search across your local songs, albums and playlists, accent-insensitive;
- artwork it has stored, in whatever size Cider asks for;
- lyrics it has saved;
- playback of every song you have downloaded or linked to a local file.
Songs without local audio keep their place in the lists, but Cider shows them as unavailable and skips them when it builds a queue, so playback doesn’t stop halfway through an album. Requests the proxy can’t answer get an empty but valid response, so Cider’s pages still load.
When Apple Music is reachable again, the proxy goes back to forwarding and the activity list says so. To try offline mode without disconnecting, set force_offline = true in the [connectivity] section of the config.
Library sync
The proxy needs your Apple Music session to sync anything. It picks up the tokens from Cider’s own requests, so use Cider once while online with the proxy connected.
After that it fetches your whole library from Apple Music: every library playlist and album with its complete track list, and your Songs tab. It syncs when the app starts, every 30 minutes, when it sees new tokens, when Apple Music becomes reachable again, and when you choose Refresh library in the Library page’s menu. It doesn’t sync while offline. A sync is saved only when every request succeeded, so a failed or interrupted sync never leaves you with half a library.
Songs page
Settings > Library > Songs page decides what Cider’s Library > Songs page lists, online and offline:
- Added to library (the default): only the songs you added to your library yourself, the same list Apple Music shows.
- Every song: every song in your library, including every song of your library playlists and albums. The proxy answers this list itself, online too.
Only that one listing changes. Playlists, albums, search and playback are the same either way.
The Library page
The Library page shows your synced albums and playlists, and every song in them. Use the search button to search it, and the filters to show only songs missing audio or missing lyrics. Open an album or playlist to see its songs.
Each song row has a download control and a menu with:
- Download, Pause download, Resume download or Retry download, depending on its state;
- Link to local file… to play your own audio file for this song, or Unlink local file to stop;
- Fetch lyrics and Choose lyrics file…;
- Remove download… to delete the downloaded audio.
An album or playlist has Download, Fetch lyrics for all songs and Remove download… for all of its songs. The Library menu has Refresh library, Download all missing audio and Fetch all missing lyrics.
Downloads
A download asks Apple Music for the song the same way Cider does when it plays it, gets a Widevine license, downloads the encrypted audio and decrypts it on your computer, using a Widevine device that ships with the app. The result is a plain AAC .m4a file (256 kbps when Apple offers it, otherwise 64 kbps) in the media folder of the app’s data folder. After a download finishes, the app looks up lyrics for the song (you can turn that off).
The download needs the Apple Music session the proxy captured from Cider. If Apple says the session ended, the song fails with “Apple Music sign-in expired: play a song in Cider while online, then retry”. Do what it says.
The Downloads panel lists the queue. You can pause and resume everything, retry the failed downloads, clear the finished ones, and add any song, album or playlist by pasting its Apple Music link or ID. Failures that are likely temporary (Apple rate limits, server errors, network errors) are retried automatically with growing pauses. A song marked “Can’t download yet” can’t be downloaded this way and isn’t retried until you ask.
For music videos, the app downloads the audio. A music video also offers to download the song from the album instead; its edit can differ from the video’s.
Settings that affect downloads, under Settings > Library:
- Download played songs: Off (the default), Right away (download every song as you play it), or When idle (queue them, and download once nothing has played for 30 seconds).
- Simultaneous downloads: 1 to 6, default 2. Apple refuses licenses when too many are requested at once, so 2 is the most reliable.
- Overwrite audio: download or import again over audio a song already has, instead of skipping it.
- Detail level: Full keeps every attribute Apple sends for a song, which makes the library, search and lyrics richer offline. Minimal keeps only the id, title, artist, album, duration and artwork.
Using your own Widevine device
To use a different Widevine device, put it in the app’s data folder as device.wvd (see Files and folders) and restart the app. If the file can’t be read, the app falls back to the built-in device. If it can be read but isn’t a valid device file, downloads are turned off until you fix or remove it.
Lyrics
When Cider fetches lyrics from Apple while online, the proxy saves them. Offline it serves the saved lyrics. For songs Apple has no lyrics for, you can fetch them from other providers. These are asked in this order by default:
- Apple Music
- Cider Community (lyrics submitted by Cider users)
- AMLL TTML DB
- Musixmatch (through Cider’s lyrics service)
- NetEase Cloud Music
- Kugou
- LRCLIB
Under Settings > Lyrics you can turn providers off and change the order. The other options there:
- Search until: providers are asked in order until lyrics of this quality turn up: Word-synced (best), Line-synced or Any lyrics. If none do, the best lyrics found are kept.
- When a lookup fails (rate limit, server error, timeout): Skip, retry at the end asks again for the skipped songs once the rest are done; Wait and retry waits and asks the same provider again before moving on; Skip leaves the song without lyrics until you fetch again. “No lyrics found” is not a failure.
- Always use downloaded lyrics: while online, answer Cider’s lyrics requests with the saved lyrics instead of asking Apple. Songs without saved lyrics still get Apple’s.
- Fetch after downloading: look up lyrics for every song once its download finishes.
- Overwrite lyrics: when fetching for a whole album or playlist, or after a download, look up songs that already have lyrics again. Apple lyrics are always kept. Fetching lyrics for a single song always looks them up.
More options has the providers the failure rule applies to (the others always wait and retry), the pause between two LRCLIB lookups, and how many retry passes run at the end.
Your own audio and lyrics
Link to local file… in a song’s menu plays your own file for that song instead of Apple’s stream. Supported types are m4a, mp3, flac, aac, alac, wav, ogg and opus. The file stays where it is; the app only remembers its path.
Choose lyrics file… sets lyrics from a TTML or LRC file. Lyrics you choose this way always win: Cider gets them online and offline, whatever the other lyrics settings say.
The add button on the Library page (Add a song, album or playlist) adds a song, album or playlist of your own. A song can have a title, artist, album, artwork, a release date, a description and more, an audio file or the audio of another Apple Music song (by its ID), and a lyrics file. It can go into one of your albums or playlists, or into a new album. These items show up in Cider like the rest of your library: in the library lists, in search and in playback, online and offline. Your own items have Edit details… and Delete… in their menu, and songs in your own playlists can be moved up and down.
Start at login and the tray
Settings > Startup has Start with the system, which launches the app when you sign in, and Start minimized, which starts it hidden in the tray. The login entry always starts the app minimized.
The tray menu (the menu bar on macOS) shows the proxy’s status and has Passthrough and Capture switches, Open window and Quit. On Windows and Linux, clicking the icon opens the window. The icon changes with the mode.
Closing the window hides it to the tray. Quit stops the proxy and exits.
On Linux the tray needs a StatusNotifierItem host. KDE has one; on GNOME install the “AppIndicator and KStatusNotifierItem Support” extension. Without one, the app shows a one-time hint, the minimize button minimizes, the close button quits, and “start minimized” starts minimized instead of hidden. If the tray goes away while the window is hidden (for example when the panel restarts), the window comes back.
Only one copy of the app runs at a time. Starting it again brings up the window of the one that is running. On macOS, opening the app again from Finder, Launchpad or Spotlight doesn’t do this; use Open window in the menu bar icon. An installed copy and a portable copy have separate data, so they can run side by side.
Settings
Most of the Settings page is described above. The rest:
- Proxy > Port: the port the proxy listens on. Changing it restarts the proxy; point Cider at the new port too.
- Storage: open the data folder or the capture folder; Clear cache deletes cached Apple Music responses and artwork, and keeps your downloaded audio, linked files and your own songs; Uninstall certificate removes the local certificate from your system (Cider then stops working through the proxy in Active mode); Remove all data… is described in Uninstalling.
Settings are saved to config.toml. Configuration lists every option, including a few that are only in the file.
Configuration
The app keeps its settings in a TOML file, config.toml:
| Install | Location |
|---|---|
| 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) |
| Portable | data/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
| Key | Type | Default | Effect |
|---|---|---|---|
mode | "active" or "passthrough" | "active" | Mode the proxy starts in. passthrough forwards everything untouched. |
capture | bool | false | Write 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_concurrency | integer | 0 | Downloads that run at once, 1 to 6. 0 means the default, 2. Larger values are capped at 6. |
overwrite_audio | bool | false | Replace audio a song already has when downloading or importing, instead of skipping it. |
overwrite_lyrics | bool | false | When fetching lyrics for a collection or after a download, look up songs that already have lyrics again. Apple lyrics are always kept. |
start_with_os | bool | false | Start the app when you sign in. |
start_minimized | bool | false | Start hidden in the tray (minimized when there is no tray). |
cider_config_path | path | not set | Cider’s client-options.yml, when you picked it with Choose config file… (Windows). |
tray_hint_dismissed | bool | false | The one-time “no system tray” hint on Linux was dismissed. |
[proxy]
| Key | Type | Default | Effect |
|---|---|---|---|
bind_address | IP address | "127.0.0.1" | Address the proxy listens on. The default keeps it reachable from this computer only. |
port | integer | 8000 | TCP 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.
| Key | Type | Default | Effect |
|---|---|---|---|
enabled | bool | true | Run the monitor. When off, the proxy assumes it is online (a failed request still gets an offline answer). |
probe_url | string | "https://amp-api.music.apple.com/" | URL checked with a HEAD request. Any HTTP response counts as online. |
interval_secs | integer | 15 | Seconds between checks (at least 1). |
timeout_secs | integer | 5 | Timeout of one check in seconds (at least 1). |
force_offline | bool | false | Treat Apple Music as unreachable, so every request is answered from your computer. Useful to see what works offline. |
[library]
| Key | Type | Default | Effect |
|---|---|---|---|
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]
| Key | Type | Default | Effect |
|---|---|---|---|
providers | array of { id, enabled } | all seven, enabled | Lyrics 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_providers | array of provider ids | all seven | Providers 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_download | bool | true | Look up lyrics for each song once its download finishes. |
lrclib_spacing_ms | integer | 250 | Milliseconds between two LRCLIB lookups (at most 10000). |
retry_passes | integer | 3 | Retry passes over skipped songs with skip_and_retry_later (1 to 10). |
always_use_downloaded | bool | false | While 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
| Option | Effect |
|---|---|
--version | Print cider-offline <version> and exit. |
--minimized | Start in the tray, like start_minimized. The login entry passes it. |
--remove-all-data | Undo the system changes and delete the app’s files, then exit. See Uninstalling. |
--uninstall-cleanup | Undo the system changes only, then exit. |
--dry-run | With 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.
Files and folders
The app uses three folders: a config folder for settings, a data folder for your library and downloads, and a cache folder for things it can fetch again. Config and data are kept apart so settings can roam with your user profile while the large files stay on this computer. Everything in the cache folder can be deleted at any time.
Where they are
| System | Config | Data | Cache |
|---|---|---|---|
| Windows | %APPDATA%\cider-offline\CiderOffline\config | %LOCALAPPDATA%\cider-offline\CiderOffline\data | %LOCALAPPDATA%\cider-offline\CiderOffline\cache |
| macOS | ~/Library/Application Support/sh.cider-offline.CiderOffline | same folder as config | ~/Library/Caches/sh.cider-offline.CiderOffline |
| Linux | ~/.config/cideroffline | ~/.local/share/cideroffline | ~/.cache/cideroffline |
On Linux the XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_CACHE_HOME variables move these folders if they are set. On macOS the config and data folders are the same, so config.toml sits next to store.sqlite.
Settings > Storage > Data folder opens the data folder.
What’s in them
| Folder | Contents |
|---|---|
| Config | config.toml (see Configuration) |
| Data | store.sqlite (the library database, with its -wal and -shm files while the app runs), media/ (downloaded audio), lyrics/ (saved lyrics), ca/ (the local certificate and its private key), captures/ (only if capture was turned on), instance.lock (makes sure only one copy runs), and device.wvd if you added one |
| Cache | artwork/ (cover art), logs/ (log files) |
The database stores the paths of files in the data folder relative to it (for example media/123.m4a), so you can move the data folder, or plug a portable drive in under a different drive letter, without breaking the library. Files you picked from elsewhere, such as a linked audio file, are stored with their full path and stay where they are.
Portable mode
If a folder named data sits next to the program, the app runs in portable mode and keeps everything inside that folder:
| What | Where |
|---|---|
| Config | data/config/config.toml |
| Data | directly in data/ |
| Cache | data/cache/ (so logs are in data/cache/logs/) |
“Next to the program” means:
- Windows: the folder that contains
cider-offline.exe; - macOS: the folder that contains
Cider Offline.app; - Linux: the folder that contains the AppImage.
The portable archives come with an empty data folder (holding a .keep file so unzip tools don’t drop it). The installers never create one. To switch a copy back to the normal folders, remove its data folder.
On macOS a quarantined app is run from a hidden read-only location where data can’t be found; see Installation.
Custom Widevine device
A file named device.wvd in the data folder replaces the Widevine device built into the app:
- Windows:
%LOCALAPPDATA%\cider-offline\CiderOffline\data\device.wvd - macOS:
~/Library/Application Support/sh.cider-offline.CiderOffline/device.wvd - Linux:
~/.local/share/cideroffline/device.wvd - Portable:
data/device.wvdnext to the program
The app reads it when it starts, so restart the app after adding or replacing it.
Logs
The app writes one log file per day, cider-offline.<date>.log, to the logs folder in the cache folder, and keeps the last seven:
- Windows:
%LOCALAPPDATA%\cider-offline\CiderOffline\cache\logs - macOS:
~/Library/Caches/sh.cider-offline.CiderOffline/logs - Linux:
~/.cache/cideroffline/logs - Portable:
data/cache/logs
Outside these folders
A few things live elsewhere on your system:
- the trusted certificate, in your system’s certificate store (see Installation);
- the start-at-login entry, if you turned it on;
- on Windows, the two proxy lines in Cider’s
client-options.yml, if you used Route Cider through this proxy; - text reports in your temporary folder:
cider-offline-cleanup-*.txtfrom a cleanup run that was a dry run or had a failed step, andcider-offline-removal-report-*.txtwhen Remove all data couldn’t delete something.
Uninstalling explains how to remove all of it.
Uninstalling
Besides its own folders, the app may have changed three things on your system: it trusted its certificate, it may have added a start-at-login entry, and on Windows it may have turned on Cider’s proxy setting. Deleting the program alone leaves those behind. The ways to remove the app below undo them as well.
Windows installer
Uninstall the app from Settings > Apps > Installed apps (or Control Panel > Programs). The uninstaller has a checkbox, unticked by default: Also remove my downloaded music and settings.
- Unticked, the uninstaller removes the certificate, turns off start at login, turns off Cider’s proxy setting if it points at this proxy, and removes the program. Your library, downloads and settings stay, so a later install picks them up again.
- Ticked, it also deletes the config, data and cache folders.
If the app is still running, the uninstaller offers to close it first. If the cleanup fails, it shows a message with the path of the removal script you can run instead (see Removal scripts).
A silent uninstall (/S) leaves the box unticked. Installing a new version over an old one runs none of this cleanup, so the certificate, the login entry and Cider’s proxy setting stay in place.
macOS and Linux
There is no uninstaller that runs the cleanup. Before you delete the app or remove the package, open Settings and use Remove all data…, or run the cleanup from a terminal (see Command-line cleanup). Then delete Cider Offline.app from Applications, or remove the package with your package manager (sudo apt remove cider-offline, sudo dnf remove cider-offline, sudo pacman -R cider-offline), or delete the AppImage.
Portable build
Everything the app stores is inside its data folder, but the certificate, the login entry and Cider’s proxy setting are not. Use Settings > Remove all data… first, then delete the whole folder.
Remove all data
Settings > Storage > Remove all data… removes everything the app created:
- It removes the certificate from the trust store, turns off start at login, and turns off Cider’s proxy setting when it points at this proxy (Windows only; on macOS and Linux the app never changed Cider’s settings).
- The app quits. After the proxy has stopped, it deletes the config, data and cache folders. On Windows it also removes the empty
cider-offline\CiderOfflinefolders above them.
The confirmation dialog names the folders it will delete. In a portable copy it deletes only the app’s own entries inside data (config, cache, store.sqlite and its -wal, -shm and -journal files, media, lyrics, ca, captures, instance.lock, device.wvd and .keep). The data folder itself and anything else you keep in it stay.
Files you picked from elsewhere, such as linked audio files or lyrics files, are never touched.
If removing the certificate fails, the ca folder is kept so the certificate can still be removed later with --uninstall-cleanup. If a step fails after the window has closed, the app writes a cider-offline-removal-report-*.txt file to your temporary folder and opens it.
Command-line cleanup
The same cleanup can run from a terminal:
| Command | Effect |
|---|---|
cider-offline --uninstall-cleanup | Remove the certificate, turn off start at login, turn off Cider’s proxy setting (Windows). Keeps all files. This is what the Windows uninstaller always runs. |
cider-offline --remove-all-data | The above, then delete the app’s files, like Remove all data. |
add --dry-run | Print the steps it would take and change nothing. |
Where the program is:
- Windows:
"%LOCALAPPDATA%\Cider Offline\cider-offline.exe" - macOS:
"/Applications/Cider Offline.app/Contents/MacOS/cider-offline" - Linux packages:
cider-offline(in/usr/bin) - AppImage: the
.AppImagefile itself
The app must not be running. A cleanup run waits up to 5 seconds for a quitting app to let go, and otherwise stops with “Cider Offline is running; quit it first”. It prints every step and exits with an error if any step failed.
The Windows release build has no console, so its output can’t be seen. That’s why a dry run, or a run with a failed step, also writes the steps to a new cider-offline-cleanup-*.txt file in the temporary folder (on every system) and prints its path.
Removal scripts
If the app is already gone and its certificate is still trusted, the installers ship scripts that remove it:
| System | Script | Notes |
|---|---|---|
| Windows | %LOCALAPPDATA%\Cider Offline\scripts\remove-ca-windows.ps1 | Run with powershell -ExecutionPolicy Bypass -File remove-ca-windows.ps1. Windows asks you to confirm each removal. |
| macOS | Cider Offline.app/Contents/Resources/scripts/remove-ca-macos.sh | Asks for your password to change trust settings. |
| Linux | /usr/lib/cider-offline/scripts/remove-ca-linux.sh | Needs certutil. Removing the system-wide copy asks for your password through polkit. |
The scripts remove only the certificate, not the login entry or Cider’s proxy setting. Copy the script somewhere else before you uninstall if you want to run it afterwards.
You can also remove the certificate by hand. It is called Cider Offline CA. On Windows it is in the current user’s Trusted Root Certification Authorities (certmgr.msc), on macOS in the login keychain (Keychain Access), and on Linux in ~/.pki/nssdb and the system trust anchors.
Troubleshooting
Most problems show up on the Overview page: in the proxy status, the certificate row, the Cider row or the activity list. For anything else, look in the logs.
Cider shows network errors or loads nothing
In Active mode Cider only accepts the proxy’s connections if the certificate is trusted. If the Certificate row says “Cider will reject the proxy’s HTTPS traffic until the certificate is trusted”, click Install, confirm the system prompt, and restart Cider.
On Linux:
- If the row reports that
certutilwas not found, install the NSS tools (libnss3-toolson Debian and Ubuntu,nss-toolson Fedora,nsson Arch) and click Install again. - If you installed Cider as a Flatpak or Snap after trusting the certificate, its certificate database doesn’t have it yet. Click Check again, then Install.
To check whether the proxy is the cause at all, switch to Passthrough. If Cider works then, the problem is the certificate or the cache, not the connection.
The proxy doesn’t start
The status says “Proxy stopped” and the activity list shows “Could not start the proxy: …”. The most common cause is “could not listen on 127.0.0.1:8000”, which means another program already uses that port. Pick a different port under Settings > Proxy > Port, then point Cider at the new port (on Windows, turn Route Cider through this proxy off and on again).
Requests seen stays at 0
Cider isn’t sending its traffic through the proxy.
- Windows: check that Route Cider through this proxy is on. Cider reads the setting only when it starts, so restart Cider if you changed
client-options.ymlyourself. - macOS and Linux: the
--proxy-serveroption applies only to a Cider started with it. Quit Cider completely and start it with the command shown on the Overview page. - If you changed the port, Cider must use the new one.
Windows: Cider’s settings file was not found
The app looks for %APPDATA%\sh.cider.dotnet\client-options.yml. If your Cider keeps it elsewhere, click Choose config file… and pick it. “Cider did not close in time” means Cider didn’t exit when asked; close it yourself and turn the switch on again.
The library is empty or out of date
The library sync needs the Apple Music session tokens that the proxy picks up from Cider. Use Cider online through the proxy (open your library or play a song), then choose Refresh library in the Library page’s menu. The sync doesn’t run while offline, and a sync that fails part way through changes nothing, so the old library stays until a full sync succeeds.
Songs are greyed out offline
Offline, only songs with local audio can play: downloaded ones and ones linked to a local file. Use the Library page’s “missing audio” filter to find the others, and download them while you’re online.
Downloads fail
- “Apple Music sign-in expired: play a song in Cider while online, then retry”: Apple no longer accepts the session the proxy captured. Play something in Cider while online, then retry the download.
- “Can’t download yet”: Apple’s answer for this song doesn’t include audio the downloader can handle. It isn’t retried automatically.
- Many downloads failing with license errors at once: lower Settings > Library > Simultaneous downloads to 2 or 1. Apple refuses licenses when too many are requested together.
- “No “drm” downloader is registered; drop a device.wvd file in the data folder and restart.“: the
device.wvdin the data folder isn’t a valid device file. Replace or remove it and restart the app.
Temporary failures (rate limits, server and network errors) are retried on their own; the row shows when the next attempt is.
Lyrics are missing
Fetch them with Fetch lyrics on the song, or Fetch all missing lyrics in the Library menu. If a provider keeps failing with rate limits, raise the LRCLIB spacing or choose Wait and retry under Settings > Lyrics. Lyrics you chose from a file always take priority over everything else.
Starting the app again does nothing
Only one copy runs at a time, and starting it again shows the window of the running copy. If you don’t see it, look for the tray icon. On macOS, opening the app again from Finder or Spotlight doesn’t show the window; use Open window in the menu bar icon.
On Linux without a tray host (GNOME without the AppIndicator extension), the app shows a hint about it, and closing the window quits the app.
macOS: the portable copy uses my normal folders
The Overview page says macOS is running the copy from a temporary read-only location. Quit the app, run xattr -dr com.apple.quarantine on the unzipped folder, and open it again. See Installation.
My settings were reset
If config.toml has a syntax error, the app starts with the defaults and logs invalid config; using defaults. Fix the file (or delete it) with the app closed. See Configuration.
Checking offline behaviour
To see what works offline without disconnecting, quit the app, set force_offline = true under [connectivity] in config.toml, and start it again. Set it back to false when you’re done.
Logs
The app logs to a daily file in the logs folder of its cache folder, and keeps the last seven files:
- Windows:
%LOCALAPPDATA%\cider-offline\CiderOffline\cache\logs - macOS:
~/Library/Caches/sh.cider-offline.CiderOffline/logs - Linux:
~/.cache/cideroffline/logs - Portable:
data/cache/logsnext to the program
The default level is info (with the proxy library’s own messages at warn). For more detail, set RUST_LOG before starting the app, for example RUST_LOG=info,cider_offline_core=debug. The targets are cider_offline (the app), cider_offline_core (proxy, library, lyrics, downloads queue), cider_offline_trust (certificate) and cider_offline_download (the downloader).
The app never logs token values, but logs can contain song titles, URLs and file paths. When you share logs in a bug report, paste only the relevant lines and remove anything that looks like a token, a cookie or an Authorization header. If the problem is in what Cider receives, a capture (Overview > Capture Apple traffic to disk) helps too; check it the same way before sharing.
Bugs go to the issue tracker. Report security problems privately through the repository’s Security tab instead.
How it works
Cider Offline is an HTTPS proxy that sits between Cider and Apple Music, with a local database behind it and a desktop window in front.
your computer
+-----------------------------------------------------------+
| |
| +-------+ +-----------------------+ | +-------------+
| | Cider | ---> | proxy on 127.0.0.1 | --- online ----------> | Apple Music |
| +-------+ | | | +-------------+
| | Apple hosts: | |
| | online: forward, | |
| | cache, rewrite | |
| | offline: answer | |
| | from local data | |
| | other hosts: | --- tunnel ----------> rest of the
| | tunnel untouched | | internet
| +-----------------------+ |
| | ^ |
| v | |
| +------------------+ +-----------------------+ |
| | store.sqlite, | | window and tray icon | |
| | media/, lyrics/, | | (settings, library, | |
| | artwork/ | | downloads) | |
| +------------------+ +-----------------------+ |
+-----------------------------------------------------------+
The proxy
Cider is configured to use the proxy for HTTP and HTTPS. For most hosts the proxy only opens a tunnel and passes the encrypted bytes through. For Apple Music hosts (music.apple.com, itunes.apple.com and mzstatic.com, plus blobstore.apple.com while offline) it terminates TLS with a certificate signed by its local certificate authority, which is why Cider has to trust that authority. In Passthrough mode it doesn’t do even that: everything is a tunnel.
Each intercepted request runs through a fixed chain of steps:
- Token capture: the Apple Music developer token and user token Cider sends are saved, so the app can sync the library and download songs on its own later. Token values are never logged.
- Library injection: songs, albums and playlists you created in the app are merged into Apple’s answers (library lists, lookups, search), so Cider shows them like any other item.
- Response cache: successful
GETanswers of the Apple Music API and artwork are stored. Auth, token, license and playback endpoints are never cached. The song metadata in those answers also feeds the local library. - Lyrics: Apple’s lyrics are saved as they pass. Your own lyrics, or saved lyrics with “Always use downloaded lyrics” on, are answered without asking Apple. Songs that have local lyrics are marked as having lyrics even where Apple says they have none.
- Local playback: when Cider asks to play a song that has a local file, the answer points Cider at a media URL that the proxy serves itself, with seeking support. It sits on Apple’s playback host, so it needs no extra port or certificate, and the request never leaves your computer.
- Offline responder: when Apple Music is unreachable, it answers from the local data.
Online
Online, requests go to Apple, and the steps above watch and adjust the answers on the way back. A separate library sync uses the captured tokens to fetch your complete library from the Apple Music API, because what Cider happens to request is never the whole library (first pages, partial lists). The sync replaces the stored library in one transaction, and only if every request succeeded.
Offline
A connectivity monitor checks Apple Music every 15 seconds. When it can’t be reached, or a forwarded request fails, the offline responder answers instead:
- artwork from the stored images, in whatever size and format Cider asks for;
- the API endpoints the local library can answer (library lists and lookups, collection tracks, search, catalog lookups for local songs), built from the synced library and honouring Cider’s paging and
includeparameters; - other requests from an exact match in the response cache;
- anything else with an empty but valid document, so Cider’s pages still render.
Songs without local audio keep their place in lists but lose their play parameters, so Cider shows them as unavailable instead of failing in the middle of a queue.
Downloads
Downloading is separate from the proxy. A queue in the core crate decides what to fetch, how many downloads run at once, when to retry and how long to wait; it is the only place that tracks download state. It hands each song to a downloader.
The downloader in this project does what Cider’s web player does when it plays a song: it asks Apple’s playback service for the song’s stream, gets a Widevine license for it using a Widevine device that ships with the app (or your own device.wvd), downloads the encrypted audio, decrypts it on your computer and writes a plain AAC .m4a into the media folder. Each song needs its own license, and Apple refuses licenses when too many are requested at once, which is why the queue spaces downloads out and retries temporary failures.
After a download, the queue records the file in the library and, if enabled, fetches lyrics.
The crates
The code is a Cargo workspace:
| Crate | Folder | What it does |
|---|---|---|
cider-offline | crates/app | The desktop app: Slint window, tray icon, settings, Cider integration, cleanup, and the command-line checks. Owns the tokio runtime. |
cider-offline-core | crates/core | The proxy engine: interception, the interceptor chain, offline responder, storage (SQLite), library sync, lyrics providers, local media, and the download queue with its Downloader trait. |
cider-offline-trust | crates/trust | Creates the local certificate authority and installs it into or removes it from the system trust stores. |
cider-offline-download | crates/download | The Widevine downloader that plugs into the core’s Downloader trait. |
icon-gen | packaging/icons/gen | A small tool that renders the SVG icon sources into the PNG and ICO files the build uses. Not a workspace member. |
The dependencies run in one direction: the app uses core, trust and download; download uses core; core uses trust. None of the libraries knows about the UI.
The split keeps each piece testable on its own. The core runs without a window, so it can be tested headless and driven by the command-line checks. The trust crate holds all the platform-specific certificate handling (Windows certificate store, the macOS security tool, certutil and pkexec on Linux) behind one interface. The downloader is kept out of the core on purpose: the core contains no license or decryption code, only the trait any downloader implements, plus a built-in one that imports a local file. The icon generator pulls in an SVG renderer, which normal builds don’t need, so it lives outside the workspace and the generated icons are committed.
The app
The main thread runs the Slint event loop (macOS requires the UI on the main thread), and a multi-threaded tokio runtime on background threads runs the proxy and all storage, network and file work. The two sides talk through a command handle and a stream of status events, without shared mutable state.
A lock file in the data folder (instance.lock) makes sure only one copy runs per data folder. A second launch connects to the running copy over a local socket, asks it to show its window, and exits.
Development
How it works explains the architecture and the crates. This page is about building, testing and releasing.
Prerequisites
You need a stable Rust toolchain no older than the rust-version in the workspace Cargo.toml (currently 1.95). The workspace uses the 2024 edition.
- Windows: the MSVC toolchain (Visual Studio Build Tools with “Desktop development with C++”). The GNU toolchain is not supported. Building for 32-bit Windows (
i686-pc-windows-msvc) also needs NASM onPATH, and building for ARM64 (aarch64-pc-windows-msvc) needsclang-cl, which comes with Visual Studio’s LLVM component. - macOS: the Xcode command-line tools (
xcode-select --install). - Linux:
pkg-configand the development packages for xcb, xkbcommon and fontconfig, pluslibnss3-toolsfor the trust store tests. On Debian and Ubuntu,packaging/ci/install-linux-deps.shinstalls exactly what CI uses. The app needs no GTK.
Build and run
cargo build -p cider-offline
cargo run -p cider-offline
A debug build on Windows keeps its console window, so log output is visible; release builds are GUI-only.
The app logs through tracing. The default filter is info,hudsucker=warn; set RUST_LOG to change it:
RUST_LOG=info,cider_offline_core=debug cargo run -p cider-offline
In PowerShell, set it first with $env:RUST_LOG = "info,cider_offline_core=debug". The useful targets are cider_offline (the app), cider_offline_core, cider_offline_trust, cider_offline_download and hudsucker (the proxy library). Logs also go to the daily file described in Files and folders.
A debug build uses the same folders as an installed copy, so it works on your real library and settings. To keep it separate, create an empty data folder next to the built executable (target/debug/data); the build then runs in portable mode.
Checks before a change is done
These three must pass:
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
CI (.github/workflows/ci.yml) runs exactly these checks, on the whole workspace, on every push and pull request, on Linux x86_64, Linux ARM64, Windows and macOS.
The workspace forbids unsafe code and warns on missing docs and on Clippy’s pedantic lints, so -D warnings makes those hard errors. The app crate only denies unsafe instead of forbidding it, for two scoped exceptions: the code Slint generates from the .slint files, and one Windows call (AllowSetForegroundWindow, so a second launch can bring the running window to the front).
Headless checks
The app binary has a few modes that run against your real data without opening a window, for checking library, offline and download behaviour against the live Apple Music API. They need tokens the proxy has already captured from Cider, and they print no token values. Run them with the app closed, from a debug or release build:
| Command | What it checks |
|---|---|
cider-offline --library-check [--fresh] [--import-tokens <store.sqlite>] | Runs one library sync and compares the result with what the Library page reads. --fresh syncs into a new temporary database that has only the tokens, --import-tokens copies the tokens from another database first. |
cider-offline --offline-check [--captures <dir>] [--baseline] [--verbose] | Starts the proxy forced offline on a free port, over a temporary copy of the database, and replays captured Cider requests against it through real TLS. Then checks the library contents, artwork, search, playback, the Songs page setting and lyrics, offline and online. --captures defaults to the app’s captures folder. |
cider-offline --download-check <catalog id>... [--concurrency N] | Runs the given songs through the real download queue and downloader, printing every queue event. |
cider-offline --lyrics-check [--collection NAME] [--default-settings] [--overwrite] | Counts songs with lyrics, runs “Fetch all missing lyrics” (or one collection’s fetch) and counts again. |
cider-offline --lyrics-check --provider <id|all> [--collection NAME]... [--limit N] [--ids ID...] [--show-ttml] | Asks one provider (or each in turn) about some songs and prints what it found. Stores nothing. |
cider-offline --perf-check [--collection NAME] | Times the paged library queries, the cover prefetch and opening a large playlist. |
cider-offline --screenshot out.png [--page library|songs|detail|overview|settings] [--collection NAME] ... | Renders one view with the real window and data and saves it as a PNG. See crates/app/src/ui/shot.rs for all options. |
--library-check doesn’t need to know your library: it checks that the Library page shows exactly the playlists and albums Apple returned, each once and with its full track list in Apple’s order, that albums come after playlists, and that every cover loads. --perf-check opens the largest collection of the Apple Music library unless --collection names one, and --screenshot --page detail opens the first one.
The --offline-check replay needs captures, so turn on Capture Apple traffic to disk and use Cider for a while first.
Building packages
Packages are built with cargo-packager 0.11.8 (the NSIS template in packaging/nsis/ is a patched copy of that version’s) and, for the .rpm, cargo-generate-rpm. Install them with:
cargo install cargo-packager --version 0.11.8 --locked
cargo install cargo-generate-rpm --locked
Then, from the repository root:
cargo build --release --locked -p cider-offline
cargo packager --config crates/app/Packager.toml --formats nsis # Windows
cargo packager --config crates/app/Packager.toml --formats app,dmg # macOS
cargo packager --config crates/app/Packager.toml --formats appimage,deb,pacman # Linux
cargo generate-rpm -p crates/app # Linux .rpm
The packages land in target/packages (the .rpm in target/generate-rpm). Packager.toml reads the binary from target/release. When you build for another target with --target, change binaries-dir in Packager.toml to that target’s folder; the release workflow does the same.
What goes into the packages:
crates/app/Packager.toml: name, version, icons, the bundled removal scripts, the per-user NSIS installer, the macOS minimum version (11.0) and the Linux package dependencies.packaging/nsis/installer.nsi: the Windows installer template, with the “Also remove my downloaded music and settings” checkbox and the cleanup calls described in Uninstalling.packaging/macos/Info.plist: merged into the app’s plist; makes it a menu bar app without a permanent Dock icon.packaging/scripts/: the certificate removal scripts.packaging/portable/README.txt: the readme of the portable archives.packaging/icons/: generated icons. After editing an SVG inpackaging/icons/src/, regenerate them withcargo run --manifest-path packaging/icons/gen/Cargo.toml.
Releases
Releases are built by .github/workflows/release.yml when a tag starting with v is pushed:
git tag v0.1.0
git push origin v0.1.0
The workflow first checks that the tag (without its v) equals both the workspace version in Cargo.toml and the version in crates/app/Packager.toml, and stops if they differ. Then it builds:
| Runner | Targets | Output |
|---|---|---|
windows-latest | x64, x86 | NSIS setup .exe and portable .zip |
windows-11-arm | ARM64 | NSIS setup .exe and portable .zip |
macos-15 | arm64 and x86_64, joined into one universal binary | .dmg and portable .zip |
ubuntu-24.04 | x86_64 | AppImage, .deb, .rpm, Arch package with its PKGBUILD, portable .tar.gz |
ubuntu-24.04-arm | aarch64 | the same as x86_64 |
Every job runs its build with --version as a smoke test before uploading. The last job collects everything, writes one SHA256SUMS.txt, and creates a draft GitHub Release with generated notes. Review the draft and publish it by hand.
The builds are unsigned unless signing secrets are configured. With WINDOWS_CERTIFICATE_THUMBPRINT set, the Windows installer is Authenticode-signed. With the APPLE_* secrets (certificate, signing identity, Apple ID, app-specific password, team ID), the macOS app is signed with a Developer ID and notarized; without them it is ad-hoc signed.
This documentation
The documentation is an mdBook in docs/, with the pages in docs/src/ and the table of contents in docs/src/SUMMARY.md. To preview it:
cargo install mdbook --locked
mdbook serve docs --open
mdbook build docs writes the site to docs/book/, which is not committed. Pushing changes under docs/ to main runs .github/workflows/docs.yml, which builds the book and publishes it to https://cider-offline.podik.cz/docs/ with GitHub Pages.