Offline Mode

Offline Mode

QBZ can continue playing music even when you lose internet connectivity.

Audio Cache

QBZ uses a two-level caching system:

Level	Storage	Default Size	Purpose
L1 (Memory)	RAM	400 MB	Recently played tracks, instant access
L2 (Disk)	Local storage	800 MB	Persistent cache across sessions

Cached tracks play instantly without network access.

Configuring Cache Size

Adjust cache sizes in Settings > Audio > Cache:

• Increase L2 disk cache for larger offline libraries
• Decrease if disk space is limited
• Cache is stored in ~/.cache/qbz/ (or the Flatpak equivalent)

Offline Playback

When QBZ detects no internet connection:

1. The interface shows an offline indicator
2. Cached tracks remain fully playable
3. Local library files play normally (they don't need internet)
4. Qobuz-specific features (search, browse, favorites sync) are unavailable until reconnection

When connectivity is restored, QBZ reconnects automatically — no manual action needed.

Offline Scrobbling

If you have Last.fm or ListenBrainz connected, listens during offline periods are queued locally:

• Last.fm — scrobbles are stored and submitted when back online
• ListenBrainz — listen submissions are queued and sent on reconnection

No listens are lost due to temporary connectivity issues.

Manual Network Check

The offline indicator (yellow icon) in the player bar is clickable — tap it to force an immediate network check instead of waiting for the 30-second polling interval. You can also use the Check now button in Settings > Offline Mode.

Degraded Service Indicator

When Qobuz servers return repeated errors (504, 502, 503), an orange warning triangle appears in the player bar. This indicates the service is degraded but you're not fully offline.

The indicator auto-clears after 5 minutes without new server errors. You don't need to take any action — QBZ automatically retries with exponential backoff and quality fallback.

Local Library and Offline

Your local music library works fully offline since the files are stored on your machine. This makes QBZ usable as a standalone local music player even without a Qobuz subscription or internet connection.