Network Management
Audience: End users and non-technical stakeholders Last Updated: 2026-04-05 Version: 2.0.0
Overview
Llamafin includes a sophisticated network management system that continuously monitors your connection, measures network performance, and automatically recovers from connectivity issues. It combines information from your device's network hardware, your browser, and the connection to your Jellyfin server into a single, easy-to-understand status.
Unlike apps that simply check "am I online?", Llamafin understands the difference between having a network connection and having a working connection to your music server. It also passively measures your actual media streaming speed every time an image is loaded, building up a detailed history of your network performance over time.
Key Concepts
1. Unified Network Status
Llamafin combines multiple sources of network information into one clear status that determines how the app behaves:
| Status | What It Means | What You See |
|---|---|---|
| Unknown | App is still checking your network (brief, during startup) | Brief loading indicator |
| Online | Device has network AND server is connected | Normal operation |
| Connecting | Device has network, server connection in progress | "Connecting to server..." message |
| Offline (Device) | Your device has no network connection | Network alert banner, offline UI |
| Offline (Server) | Device has network but server is unreachable | Network alert banner, offline UI |
The app distinguishes between "my device has no internet" and "my server is down" so it can show you the right message and take the right action.
2. Dual-Source Network Detection
Llamafin uses two independent methods to detect your network status:
| Source | What It Detects | Speed |
|---|---|---|
| Browser Events | General internet connectivity (online/offline) | Instant |
| Capacitor Network Plugin | Detailed connection type (WiFi, cellular, ethernet) | Slight delay for full info |
When the browser detects a change (you lose or gain internet), Llamafin immediately queries the Capacitor plugin for the detailed status. This gives you both fast response times and accurate information about your connection type.
3. Connection Types
Llamafin identifies your connection type:
| Type | Description |
|---|---|
| WiFi | Connected via wireless local network |
| Cellular | Using mobile data (4G/5G) |
| Ethernet | Wired network connection (desktop) |
| None | No network connection |
| Unknown | Unable to determine connection type |
4. Passive Speed Measurement
Every time Llamafin loads an image (album artwork, artist photos, backdrop images), it measures how fast the image was received from your Jellyfin server. This happens automatically, without any action from you.
How it works:
- Image requested from server
- App records the start time
- Image received from server
- App calculates speed based on image size and download time
- Speed recorded in your history
Over time, this builds a detailed picture of your network performance during real use -- not artificial test conditions.
5. Manual Speed Test
You can run a manual speed test at any time from Settings. This test:
- Uses actual media images from your Jellyfin server (not a dedicated test endpoint)
- Measures realistic streaming performance
- Displays your speed in Mbps (megabits per second)
- Records the result in your speed history
Because the test uses real media files, the result reflects the actual speed you can expect when streaming music and viewing album art.
6. Speed History
Llamafin maintains a history of all speed measurements, including:
- Passive measurements from image loads
- Manual speed test results
- Timestamps for each measurement
- Context (what was being loaded when measured)
History Management:
- Up to 10,000 measurements stored
- Newest measurements appear first
- Automatically trimmed when limit reached
- Can be manually trimmed from Settings
- Persists across app restarts
7. Automatic Reconnection
When Llamafin detects that your network connection has been restored after being offline, it automatically reconnects to your Jellyfin server:
- Detects transition from offline to online
- Verifies your session is still valid
- Reconnects to the server
- If your music library was empty (from starting offline), automatically reloads it
This means you don't need to restart the app or manually reconnect when your internet comes back -- the app heals itself.
8. Manual Reconnection
You can also manually request a reconnection if you experience issues:
- Tap "Try Again" on the network alert banner
- Use the reconnect option in Settings
When you manually reconnect:
- If "Force Offline Mode" was active, it is automatically disabled
- The existing connection is cleanly disconnected
- A fresh connection is established
9. Force Offline Mode
Llamafin includes a Force Offline Mode in Advanced Settings that:
- Forces the app to behave as if no network is available
- Useful for testing offline functionality
- Useful when you want to browse downloaded content only
- Automatically disabled when you manually reconnect
When active, all network-dependent features are disabled, and only offline content (downloads, cached data) is accessible.
10. Server URL Change Handling
When you switch between different Jellyfin servers (e.g., from your home server to a remote server):
- The app detects the URL change
- Cleanly disconnects the existing connection
- Reconnects to the new server
You don't need to manually disconnect or restart the app when changing servers.
Configuration
Network-Related Settings
| Setting | Location | Description |
|---|---|---|
| Force Offline Mode | Settings > Advanced | Force the app to behave as offline |
| Speed Test | Settings > Network | Run a manual network speed test |
| Speed History Cap | Settings > Advanced | Maximum number of speed history entries to keep |
| Trim Speed History | Settings > Advanced (via confirmation) | Reduce speed history to a specified size |
What Network Settings Affect
| Feature | Network Impact |
|---|---|
| Streaming Quality | Higher quality settings require more bandwidth; speed history helps you choose appropriate quality |
| Downloads | Network status affects when downloads can run |
| Offline Mode | Force Offline Mode lets you preview the offline experience |
| Library Browsing | Requires network connection; shows offline UI when unavailable |
How It Works
Network Status Detection Process
1. App starts up
↓
2. Browser network events monitored (instant online/offline)
↓
3. Capacitor Network plugin listener initialised
↓
4. Initial status read from Capacitor plugin (detailed connection info)
↓
5. Both sources merged into unified status:
- Device offline → "Offline (Device)"
- Device online, server connecting → "Connecting"
- Device online, server disconnected → "Offline (Server)"
- Both connected → "Online"
↓
6. Status monitored continuously
↓
7. Any change triggers automatic response:
- Offline → Show alert, block API calls
- Online → Auto-reconnect to server
Speed Measurement Process
1. Any image requested (album art, artist photo, backdrop)
↓
2. Timer starts
↓
3. Image fetched from Jellyfin server
↓
4. Timer stops when image received
↓
5. Speed calculated: (image size in bits) / (time in seconds) = bits per second
↓
6. Result recorded in speed history with context
↓
7. History saved to storage (batched, every 2 seconds)
↓
8. Available for viewing in Settings > Network
Manual Speed Test Process
1. User taps "Run Speed Test" in Settings
↓
2. App ensures it has media items to test with (loads search suggestions if needed)
↓
3. Finds an item with album artwork available
↓
4. Downloads the image, measuring speed
↓
5. Converts speed to Mbps for display
↓
6. Shows result to user (e.g., "5.23 Mbps")
↓
7. Result recorded in speed history as "manual-speed-test"
Automatic Reconnection Process
1. Device loses network connection
↓
2. Network status changes to "offline"
↓
3. App shows network alert, blocks API calls
↓
4. Device regains network connection
↓
5. Network status changes to "online"
↓
6. App detects offline → online transition
↓
7. Checks: server is disconnected AND user session is valid
↓
8. Automatically triggers reconnection:
a. Disconnects old connection
b. Builds new connection URL with authentication
c. Connects to server
↓
9. Server connection established
↓
10. If library was empty, automatically reloads library data
↓
11. App returns to normal operation
Force Offline Mode Process
1. User enables Force Offline Mode in Settings
↓
2. Setting change detected
↓
3. Network listeners re-initialised
↓
4. Status overridden to "offline" regardless of actual connection
↓
5. App shows offline UI, blocks API calls
↓
6. User can browse downloaded content only
↓
7. When user disables Force Offline Mode:
a. Listeners re-initialised
b. Actual network status restored
c. If online, automatic reconnection triggered
Integration with Other Features
| Feature | Network Integration | Description |
|---|---|---|
| Alerts System | Network alert banner | Shows appropriate offline message based on unified status |
| Authentication | Network gating | Checks network before login attempts |
| Library | Availability gating | Shows offline UI when network unavailable; auto-reloads on reconnect |
| Search | Network gating | Prevents search when offline |
| Player | Network awareness | Adapts playback behaviour based on network status |
| Downloads | Network dependency | Downloads require network; status affects download decisions |
| Settings | Force Offline Mode | User-controlled offline override |
| Images | Speed measurement source | Every image fetch measures and records network speed |
| All API Calls | onlineOnly() operator | Gates all server requests on network availability |
Error Handling & Reliability
Network Error Scenarios
| Scenario | Detection | Recovery |
|---|---|---|
| Device loses WiFi | Browser offline event + Capacitor status change | Automatic reconnection when WiFi returns |
| Server goes down | WebSocket connection lost | Shows "server offline" message; auto-reconnects when server returns |
| Network flapping | Rapid online/offline transitions | Each transition handled independently; no special debounce |
| App starts offline | isDeviceConnected reports false | Shows offline UI; auto-connects when network available |
| Server URL changes | URL change detected via state selector | Clean disconnect and reconnect to new URL |
Speed History Reliability
| Scenario | Handling |
|---|---|
| Storage load failure | Error logged, user notified with toast, app continues with empty history |
| Storage save failure | Error logged silently (background task), no user disruption |
| History exceeds 10,000 entries | Oldest entries automatically removed |
| Manual trim | User can reduce history to specified size via Settings |
Self-Healing Features
| Feature | Self-Healing Behaviour |
|---|---|
| Network reconnection | Automatically reconnects when network returns |
| Library recovery | Reloads library if empty after reconnection |
| Force Offline Mode | Automatically disabled on manual reconnect |
| Server URL changes | Automatically disconnects and reconnects to new URL |
Technical Specifications
| Specification | Value | Description |
|---|---|---|
| Network Detection Sources | 2 | Browser events + Capacitor Network plugin |
| Connection Types Detected | 5 | WiFi, cellular, ethernet, none, unknown |
| Unified Status States | 5 | Unknown, offline (device), connecting, offline (server), online |
| Speed History Cap | 10,000 entries | Maximum stored measurements |
| Speed Save Debounce | 2 seconds | Batches rapid storage writes |
| Speed Measurement Method | Image fetch timing | Real media download speed |
| Speed Unit | Bits per second (stored), Mbps (displayed) | Network speed measurement |
| Automatic Reconnection | Yes | Triggers on offline → online transition |
| Library Auto-Recovery | Yes | Reloads if empty after reconnection |
| Force Offline Mode | Yes | User-controlled offline override |
| Manual Speed Test | Yes | Uses real media images |
| Passive Speed Monitoring | Yes | Every image download measured |
| Server URL Change Handling | Yes | Automatic disconnect and reconnect |
Known Limitations
Speed Measurement
- Point-in-time measurements: Each speed reading is a single measurement with no averaging. Individual readings may vary based on server load, image size, and network conditions.
- Image-based only: Speed is only measured when images are downloaded. Pure audio streaming does not contribute to speed history.
- No quality classification: The app does not classify your connection as "good," "poor," or "excellent." You need to interpret the raw numbers yourself.
Network Detection
- No active ping testing: The app only measures speed when downloading data. It does not actively ping the server to measure latency.
- No adaptive behaviour: The app does not automatically reduce quality on cellular connections or implement data-saving modes.
Reconnection
- No offline queue: Operations that fail while offline are not queued for retry when you come back online. Only the library is automatically reloaded.
- Library recovery only triggers if completely empty: If some library data loaded before going offline but not all, the auto-recovery will not trigger.
Related Documentation
- Offline Support -- Force Offline Mode, offline browsing, download management
- Architecture Overview -- Overall application architecture
- Settings System -- Network-related settings
- Downloads System -- Offline content management