Offline Support
Audience: End users and technical evaluators Last Updated: 2026-04-05 Version: 2.0.0
Overview
Llamafin works fully offline — no internet connection required. Your downloaded music, library browsing, search, and playback all function without network connectivity. When you reconnect, everything syncs automatically.
Key Concepts
Three Pillars of Offline Support
1. Network Status Detection
- Monitors your device's internet connection
- Tracks WebSocket connection to your Jellyfin server
- Detects WiFi vs cellular connectivity
- Measures network speed automatically
2. Storage & Persistence
- Saves your settings and preferences locally
- Stores downloaded music files securely
- Queues operations that can't complete until storage is ready
- Uses IndexedDB for reliable browser-based storage
3. Downloads & Caching
- Downloads: User-initiated permanent local copies of your music
- Caching: Automatic background caching of tracks you're about to play
- Both enable offline playback but serve different purposes
Force Offline Mode
What is Force Offline Mode?
Force Offline Mode lets you disconnect from your Jellyfin server and use Llamafin with only your downloaded content. This is useful when:
- Your server is temporarily unavailable
- You're on a slow or unreliable network
- You want to save battery by avoiding network activity
- You're traveling and want to use only downloaded music
How to Enable Force Offline Mode
From Settings:
- Go to Settings → Advanced
- Enable "Force Offline Mode"
- The app immediately disconnects from the server
- You can now browse and play only downloaded content
From Loading Screen:
- If you're stuck on the loading screen due to a slow network
- Tap "Skip and Continue Offline"
- The app enters offline mode with your downloaded content
What Works in Offline Mode
| Feature | Available Offline? | Notes |
|---|---|---|
| Play Downloaded Music | ✅ Yes | Full playback with all features |
| Browse Offline Library | ✅ Yes | Albums, artists, songs, playlists, genres |
| Search Downloaded Content | ✅ Yes | Search across all downloaded items |
| DJ Mode | ✅ Yes | Works with downloaded tracks |
| Sonic Analysis | ✅ Yes | Analysis data stored with downloads |
| Playback History | ✅ Yes | Offline play count and last played date |
| Stream from Server | ❌ No | Requires internet connection |
| Browse Server Library | ❌ No | Requires server connection |
| Server Search | ❌ No | Requires server connection |
| Remote Control Control | ❌ No | Requires network communication |
Network Status Monitoring
Dual-Source Detection
Llamafin monitors your network connection using two sources:
- Browser Events: Standard
online/offlinewindow events - Capacitor Network Plugin: Native network status detection (on mobile devices)
Why Two Sources?:
- Browser events can be unreliable on some devices
- Native plugin provides more accurate status on mobile
- Both sources merge into a single unified status
Unified Network Status
The app combines both sources into one clear status:
| Status | What It Means | What You See |
|---|---|---|
| Online | Device connected, server reachable | "Connected" |
| Connecting | Device connected, server connecting | "Connecting to Server..." |
| Offline | Device disconnected OR server unreachable | "Network Connection Lost" or "Server Unreachable" |
| Unknown | App just started, status not yet determined | Brief moment during startup |
Automatic Recovery
When Network Returns:
- Device goes from offline to online
- Llamafin detects the change automatically
- Triggers WebSocket reconnection
- If library is empty after reconnect, reloads it automatically
- You can continue streaming normally
No manual intervention needed — the app handles recovery automatically.
Offline Library
Browsing Your Downloaded Music
When offline, your library shows only downloaded content:
Available Views:
- Albums: All downloaded albums
- Artists: All artists with downloaded tracks
- Songs: All downloaded individual tracks
- Playlists: All downloaded playlists
- Genres: All genres with downloaded tracks
How It Works:
- Library pages automatically switch to offline mode when network is unavailable
- Empty states show "No items offline" instead of "No items"
- You can filter and sort offline content just like online content
- Clicking any offline item plays it locally
Offline Home Screen
When offline, the home page shows:
| Section | Content |
|---|---|
| Latest Offline Music | Recently downloaded containers sorted by date |
| Recently Played Offline | Tracks sorted by last played date |
| Frequently Played Offline | Tracks sorted by play count |
Purpose: Quick access to your most relevant offline content without browsing the full library.
Offline Search
How Offline Search Works
Always Active:
- Offline search runs alongside online search automatically
- Works even when you're online
- Results shown alongside online results
- No special configuration needed
What Gets Searched:
- Downloaded albums
- Downloaded artists
- Downloaded songs
- Downloaded playlists
- Downloaded genres
Result Types:
- Online results from server (when online)
- Offline results from downloaded content (always)
- Results merged and deduplicated
- Offline results always shown
Search Suggestions Offline
What Happens:
- Search suggestions require server connection
- When offline, suggestions are unavailable
- UI shows "Search suggestions are not available while offline"
- You can still search — just no pre-filled suggestions
Caching System
Downloads vs Caching
Downloads (User-Initiated):
- Permanent local copies you choose to save
- Appear in your Downloads section
- Available for offline playback indefinitely
- You manage them manually (add/remove)
Caching (Automatic):
- Background caching of tracks you're about to play
- Temporary local copies for faster playback
- Managed automatically by the app
- Designed to reduce buffering and improve playback
Caching Configuration
Location: Settings → Advanced → Caching
| Setting | Options | Description |
|---|---|---|
| Caching Enabled | Enabled/Disabled | Master toggle for automatic caching |
| WiFi Caching | 0, Next, 5, 10, 15, 20, 25, 40, Unlimited | How many tracks to cache ahead on WiFi |
| Cellular Caching | 0, Next, 5, 10, 15, 20, 25, 40, Unlimited | How many tracks to cache ahead on cellular |
| Cache Size Limit | Configurable | Maximum cache size |
| Network Speed Limit | Configurable | Speed threshold for caching decisions |
Caching Options Explained
| Option | Behaviour | Best For |
|---|---|---|
| 0 | No caching | Save storage space |
| Next | Cache only the next track | Minimal buffering |
| 5-40 | Cache N tracks ahead | Balanced approach |
| Unlimited | Cache as many tracks as possible | Maximum offline availability |
How Caching Works
The Process:
- You start playing music
- App checks caching settings and network status
- If caching enabled and conditions met, caches upcoming tracks
- Caches tracks in the background while you listen
- Checks every 30 seconds to maintain cache window
Guard Clauses (all must be true):
- Master caching enabled
- "Prefer downloaded media" not set to 'never'
- If on cellular, "downloads on cellular" enabled
- Caching amount not '0' for current network type
- Tracks not already cached
- Network status is 'online'
Managing Cache
Clear Cache:
- By Date: Remove items older than N days
- By Size: Remove items larger than N MB
- Access from Settings → Advanced → Caching → Clear Cache
Cache Healing:
- Scans for stale or corrupted cache entries
- Removes invalid entries
- Manual trigger from caching settings page
Manual Cache Fill:
- Forces cache to fill to target size
- Useful for pre-loading music before traveling
- Manual trigger from caching settings page
Storage Layer
What Gets Stored
Persistent Storage (survives app restarts):
- User settings and preferences
- Downloaded music files
- Analysis metadata (BPM, key, loudness)
- Playback history (offline play count, last played)
- Network speed history
Temporary Storage (cleared when app closes):
- In-memory playback state
- Active WebSocket connections
- Cached images (unless configured to persist)
Storage Capacity
What Uses Storage:
- Downloaded music files (largest)
- Cache files (variable, depends on settings)
- Analysis metadata (~1-5 KB per track)
- Visualisation data (~100KB-1MB per track)
- Settings and preferences (negligible)
Managing Storage:
- View total usage in Downloads settings
- Clear cache by date or size
- Delete downloaded containers you no longer need
Network Speed Testing
Automatic Speed Measurement
How It Works:
- Every image fetch from server measures transfer speed
- Speeds recorded in history with timestamp and context
- No manual testing required
- Helps app make smart caching decisions
What Gets Recorded:
- Speed in bits per second
- Timestamp of measurement
- Context (download-auto, stream-auto, manual-test)
Manual Speed Test
How to Run:
- Go to Settings → Network (or Advanced)
- Tap "Run Speed Test"
- App fetches test image and measures speed
- Result shown in Mbps
- Added to speed history
Why It Matters:
- Helps app decide caching behaviour
- Informs you about network quality
- Can identify network issues
Speed History
What It Shows:
- Historical speed measurements
- Up to 10,000 entries
- Sorted by most recent first
- Includes context for each measurement
Automatic Management:
- History capped at 10,000 entries
- Oldest entries removed when cap reached
- Saved to storage for persistence
- Debounced saves (2-second delay) to prevent rapid writes
Integration with Other Features
Library Management
Online vs Offline:
- Library pages check network status on load
- If online: shows server library
- If offline: shows downloaded library
- Empty messages change based on status
- No manual switching required
Search & Discovery
Dual Search:
- Offline search always executes
- Online search only when connected
- Results shown side-by-side
- Deduplication prevents duplicates
DJ Mode
Offline DJ:
- DJ Mode works with downloaded tracks
- All three modes functional offline (groupie, twofer, contempo)
- Track generation uses local analysis data
- No server calls required
Sonic Analysis
Offline Analysis:
- Analysis data stored with downloaded tracks
- No network required to view analysis
- Visualisations available offline
- Sonic Twins works with downloaded items only
Player & Queue
Offline Playback:
- Downloaded tracks play locally via Web Audio API
- All player features functional (EQ, visualizer, etc.)
- Queue management works identically
- DJ Mode generates tracks from local library
Remote Device Control
Offline Limitations:
- Remote control control requires network
- Cannot control remote devices while offline
- Local playback fully functional
- Reconnects automatically when network returns
Error Handling & Reliability
What Happens When Things Go Wrong
Network Drops During Playback:
- Currently playing track continues (already loaded)
- Next track fails if not downloaded
- UI shows "Network Connection Lost"
- Downloaded tracks continue playing normally
Server Becomes Unreachable:
- WebSocket disconnect detected
- UI shows "Server Unreachable"
- Downloaded content remains available
- Auto-reconnects when server returns
Storage Full:
- Downloads fail with error message
- Caching pauses until space available
- Settings show current storage usage
- User notified of storage issues
Self-Healing Features
- Auto-Reconnect: Detects network return and reconnects automatically
- Library Recovery: Reloads library if empty after reconnect
- Force Offline Toggle: Immediately applies offline mode when setting changes
- Storage Queue: Operations queued before storage ready replay after initialisation
- Retry Interceptor: Retries failed HTTP requests up to 3 times (5xx errors and network failures only)
Technical Specifications
| Specification | Value |
|---|---|
| Network Monitoring Sources | 2 (Browser events + Capacitor plugin) |
| Unified Network Statuses | 4 (unknown, offline, connecting, online) |
| Speed History Cap | 10,000 entries |
| Speed Test Method | Image fetch with timing |
| Cache Check Interval | 30 seconds (while playing) |
| Cache Save Debounce | 2 seconds |
| HTTP Retry Attempts | Up to 3 (5xx and network failures only) |
| Storage Backend | IndexedDB (via @ionic/storage-angular) |
| Network History Persistence | @ionic/storage |
| Force Offline Mode | Configurable in Advanced Settings |
| Caching Options | 0, Next, 5-40 tracks, Unlimited |
| Offline Library Views | 5 (Albums, Artists, Songs, Playlists, Genres) |
| Offline Search Categories | 5 (same as online) |
| Cache Clear Modes | 2 (by Date, by Size) |
Use Cases
Airplane Travel
Scenario: You're on a flight with no internet
Setup:
- Download music before traveling
- Enable offline mode if needed
- Play downloaded music normally
- Browse offline library, search, use DJ Mode
Result:
- Full music playback experience
- No network required
- All features work normally
Slow Network Recovery
Scenario: Your network is slow and the app is stuck loading
Solution:
- Tap "Skip and Continue Offline" on loading screen
- App enters offline mode immediately
- You can use downloaded content right away
- Reconnect manually when network improves
Commute with Cellular Data
Scenario: You're commuting with limited cellular data
Setup:
- Set cellular caching to 'Next' or low number
- Enable "downloads on cellular" if desired
- Download music on WiFi before commute
- Play downloaded music on cellular without using data
Result:
- Music plays from local files
- No cellular data used for streaming
- Minimal caching respects data limits
Server Maintenance
Scenario: Your Jellyfin server is down for maintenance
What Works:
- All downloaded content playable
- Offline library browsing
- Offline search
- DJ Mode with downloaded tracks
- Sonic analysis viewing
What Doesn't:
- Streaming from server
- Browsing server library
- Server search
- Remote control control
Troubleshooting
App Shows "Network Connection Lost"
Check:
- Device has internet connection (try opening a webpage)
- WiFi or cellular enabled in device settings
- Airplane mode is off
- Force Offline Mode is not enabled (unless intentional)
Try:
- Toggle Airplane mode on/off
- Force reconnect from Settings → Advanced
- Restart the app
Server Unreachable
Check:
- Jellyfin server is running
- Server URL is correct in settings
- Network can reach server (ping test)
- Firewall not blocking server port
Try:
- Access server from browser to verify it's running
- Check server URL in Llamafin settings
- Force reconnect from Settings
No Offline Content
Check:
- You have downloaded music (go to Downloads page)
- Downloads completed successfully
- Storage not full
- App has finished loading
Try:
- Download some music first
- Wait for downloads to complete
- Check storage space in settings
Caching Not Working
Check:
- Master caching enabled in settings
- "Prefer downloaded media" not set to 'never'
- If on cellular, "downloads on cellular" enabled
- Caching amount not '0' for current network type
- Network status is 'online'
Try:
- Enable caching in settings
- Increase caching amount (Next → 5 → 10)
- Check network connectivity
Related Documentation
- Downloads System - Offline music management
- Settings System - Force Offline Mode, caching configuration
- Search & Discovery - Offline search functionality
- Library Management - Offline library browsing
- Network Management - Network status and speed testing