Offline Cache Management

Offline Cache Management

QBZ provides an in-app manager for the offline track cache. Use it to see what's downloaded, free up space, and re-download specific items.

Note — QBZ is a media player, not a stream-rip tool. Cached tracks are stored as encrypted CMAF bundles, the same way official Qobuz clients (mobile and desktop) handle their offline cache. The cache is a temporary playback aid bound to your active subscription — it isn't a way to extract FLAC files for redistribution. If your subscription becomes invalid, the app removes cached content after 30 days, again matching the policy of the official clients.

Opening the Manager

Settings > Offline Playback > Manage offline cache.

The button replaces the older "Open folder" affordance, which is no longer meaningful: cache files are encrypted segment bundles on disk, not playable audio you can move around.

Layout

The rail shows every artist with at least one cached track, grouped under letter headers. The horizontal alphabet bar above the content jumps the rail to the chosen letter without changing the right pane.

Per-Album Actions

Each album row exposes a ⋯ menu:

• Re-download all tracks — re-fetches every track that's already in the cache for this album. Tracks currently downloading are skipped to avoid cancelling work in flight. This does not pull tracks you never marked offline; it only refreshes what was already cached.
• Retry failed — visible only when the album has at least one track in failed state. Re-fetches just those.
• Remove from offline — confirms with a dialog and deletes all cached tracks of the album, freeing the listed bytes.
• Go to album — navigates to the album view in the main app.

A small status badge on the right side of the row reflects the worst per-track status for the album: ✓ (all ready), spinner ring (any downloading, with average progress), or N failed (any failed).

Per-Track Actions

Click an album row to expand it (albums are expanded by default on each load). Each track row has its own ⋯ menu:

• Re-download track — single-track variant of re-download. No-op if the track is currently downloading.
• Remove from offline — confirms then frees just that track.

While a track is downloading, its status column shows a filling progress ring (the same component used elsewhere in QBZ for download buttons). Failed tracks show ⚠ and the row hover surface displays the error message.

Storage Limit

The manager enforces a configurable cache size limit to prevent runaway disk use.

• Default: 5 GB on first launch.
• Editing: click the ✎ pencil icon next to the usage bar. A modal lets you set a new limit in GB.
• Minimum: 5 GB. (Hi-res FLACs at 24-bit/192 kHz routinely run 60–100 MB each; smaller caps fill up too fast.)
• Maximum: open-ended. Set whatever your disk can comfortably afford.
• Persistence: the value is saved per user in the offline-settings DB and survives app restarts.
• Enforcement: when the cache is at or over the limit, new downloads are rejected with an informative message until you free space or raise the cap. Re-downloads of already-cached tracks are not gated (they don't grow the cache).

Failed Downloads

If "Make available offline" partially fails for a playlist or album, the manager surfaces it cleanly:

• The album row shows a red N failed badge.
• Expanding the row shows which specific tracks failed. Hovering the ⚠ icon reveals the error.
• The album-row Retry failed action targets only the failed subset.

Use the Show only failed toggle in the header to collapse the view to just the rows that need attention.

Sort Options

The Sort dropdown applies to the album list within the selected artist:

• A–Z (default) — alphabetical by album title.
• Most recent — most recently cached first.
• Largest first / Smallest first — by total size, useful when you're cleaning out space.

The artist rail itself is always alphabetical.

What the Manager Does Not Do

Cached content uses the same encryption as the official Qobuz clients and is decrypted only inside QBZ at playback time. There is no "export to FLAC" affordance. QBZ exists to fill the gap of a missing native Qobuz client on Linux, not to extract content — it is not a stream-ripper, and the cache is bound to your active Qobuz subscription on this device.

If you want offline files you can move between devices, Settings > Appearance > Show Purchases enables the Purchases module. From there you can download albums and tracks you have already purchased on Qobuz, DRM-free.

QBZ does not process payments, allow purchases through the app, or bypass regional content restrictions. Buy on Qobuz's official channels (web or store) first, then come back here to download what you own.

The manager also does not queue new downloads. To mark new content as offline, use Make available offline from any album, playlist, or track view in the main app.

Related Pages

• Offline Playback — parent page: settings panel, indicators, and the quick controls (Repair, Clear All, Show in Local Library).
• Offline Mode — the connectivity-loss path and the L1/L2 playback cache that's distinct from this manual offline cache.
• Audio Configuration — bit-perfect, DAC passthrough, and the audio backends that decide how cached audio reaches your hardware.