Offline Downloads & Storage Management
Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0
Overview
Llamafin's download system enables complete offline music listening with intelligent download management, automatic quality selection, cache management, and robust error recovery. Download albums, artists, playlists, or entire genres for playback without an internet connection.
Download Types
Container Downloads
Download organised collections of music:
| Type | What Downloads | Use Case |
|---|---|---|
| Album | All tracks + artwork + metadata | Complete album listening |
| Artist | All songs by artist + discography | Artist deep dives |
| Playlist | All playlist tracks | Curated collections |
| Genre | All songs in genre | Mood-based listening |
Individual Components
Each download includes:
- Audio Files: The actual music (highest quality available)
- Artwork: Album art, artist images, backdrops
- Lyrics: Synchronised lyrics files (if enabled)
- Metadata: Track info, artist details, album data
- Sonic Analysis: Audio fingerprints for similarity matching (if enabled)
Download Process
How Downloads Work
Step 1: Queue Download
- Click download button on any album, artist, playlist, or genre
- System validates the request
Step 2: Pre-flight Checks
- Verifies storage space available
- Checks network permissions
- Validates file system access
- Estimates total download size
Step 3: Blueprint Generation
- Creates detailed task list for every component
- Prioritises assets (images first, then audio, then extras)
- Sets up retry logic for failed components
Step 4: Download Execution
- Downloads each component systematically
- Tracks progress per item
- Retries failed downloads automatically (up to 3 attempts)
- Adapts quality based on network conditions
Step 5: Completion & Verification
- Verifies all components downloaded
- Checks file integrity
- Marks container as complete
- Available for offline playback
Smart Quality Selection (LlamaSense)
Automatic Quality optimisation
LlamaSense intelligently selects the best download quality:
How It Works:
- Measures your network speed (historical and real-time)
- Checks device capabilities (CPU, memory, storage)
- Selects optimal quality for your situation
- Chooses best download method (direct or transcoded)
Quality Thresholds:
| Network Speed | Selected Quality | Download Method |
|---|---|---|
| >20 Mbps | Maximum (original) | Direct download |
| 10-20 Mbps | 2048 kbps | Transcode if needed |
| 5-10 Mbps | 1024 kbps | Transcode if needed |
| 3-5 Mbps | 320 kbps | Transcode if needed |
| 1-3 Mbps | 128-256 kbps | Transcode if needed |
| <1 Mbps | 96 kbps | Transcode if needed |
Codec Override:
- If your device doesn't support the original format
- Automatically transcodes to compatible format
- Maintains highest possible quality
Worker Strategy
Smart Thread Selection:
- Auto Mode: Checks CPU and memory usage
- CPU >80% or RAM <250MB free → Uses background worker
- Otherwise → Uses main thread (faster)
- Always: Always uses worker (conserves main thread)
- Never: Never uses worker (maximum speed)
- Numeric: Uses worker if file > X MB
Download Methods
Direct Download
When Used:
- Server supports direct file access
- Format is compatible with your device
- Network speed is sufficient
Benefits:
- Fastest method (no server processing)
- Original quality preserved
- Lower server load
Transcoded Download
When Used:
- Format conversion needed
- Quality adjustment requested
- Device compatibility requires different format
How It Works:
- Server converts audio to compatible format
- Downloads converted segments
- Reconstructs into single file
- Saves to your device
Benefits:
- Compatible with all devices
- Adjustable quality
- Smaller file sizes
Concurrent Chunk Download
High-Performance Downloading:
- Splits file into multiple chunks
- Downloads chunks simultaneously
- Reassembles on completion
- Significantly faster than sequential
Configuration:
- Concurrent downloads: 3-8 chunks (configurable)
- Chunk size: 1-10 MB (configurable)
- Automatic retry on failed chunks
- Progress tracking per chunk
Download Management
Download Controls
| Control | Function |
|---|---|
| Pause | Temporarily stop download |
| Resume | Continue paused download |
| Cancel | Stop and delete partial download |
| Retry | Retry failed download |
| Repair | Smart-resume: only re-download missing files |
| Reset | Hard reset: start over completely |
| Refresh | Sync with server, add new tracks |
| Sync | Bidirectional sync with server |
Download States
| State | Meaning |
|---|---|
| Queued | Waiting to start |
| Downloading | Actively downloading |
| Paused | Temporarily stopped |
| Completed | All files downloaded |
| Error | Download failed |
| Paused (WiFi) | Waiting for WiFi connection |
Progress Tracking
Multi-Level Progress:
- Container Level: Overall download progress (0-100%)
- Item Level: Progress per track
- Asset Level: Progress per component (image, audio, lyrics, analysis)
- Chunk Level: Progress per download chunk (for concurrent downloads)
Progress Indicators:
- Visual progress bar
- Downloaded size / total size
- Number of files completed
- Estimated time remaining (based on current speed)
Smart Downloads
Network-Aware Behaviour
Cellular Protection:
- Downloads can be blocked on cellular data
- Automatic pause when switching to cellular
- Auto-resume when WiFi returns
- Per-setting: allow or block cellular downloads
WiFi Auto-Resume:
- Paused downloads automatically resume on WiFi
- No manual intervention needed
- Respects your download queue order
- Notifications when downloads resume
Storage Management
Pre-flight Check: Before starting download:
- Checks available storage space
- Compares to estimated download size
- Blocks if insufficient space
- Prompts to free up space if needed
Low Storage Protection:
- Monitors free space during downloads
- Auto-pauses downloads if space < 500MB
- Notifies you of low storage
- Auto-resumes when space is freed
Cache System
Rolling Cache
What It Is:
- Automatic temporary downloads around your current playback position
- Keeps upcoming tracks available offline
- Removes old tracks to save space
- Completely automatic, no manual management needed
How It Works:
[Old Tracks] → [Current Track] → [Upcoming Tracks]
↓ ↓
Deleted when Downloaded before
too far behind you reach them
Cache Window:
- Behind Current: Keeps 2 tracks for skip-back
- Ahead of Current: Downloads N tracks ahead (configurable)
- Repeat Mode: Wraps around to cache tracks from beginning
Cache Settings:
- Next Track Only: Cache just 1 upcoming track
- Numeric: Cache specific number (5, 10, 20, etc.)
- Unlimited: Cache entire remaining queue
- Separate settings for WiFi and cellular
Cache Healing
Automatic Scanner:
- Runs every 15 minutes
- Finds cache items with missing files
- Automatically re-downloads missing files
- Low priority (doesn't interfere with user downloads)
Manual Scan:
- Trigger cache healing manually
- Identifies and repairs all stale cache entries
- Useful after storage cleanup or file system changes
Reactive Healing:
- If sonic analysis fails with "file not found"
- Automatically strips stale references
- Re-triggers download of missing files
- No user intervention needed
Offline Playback
Local Match Resolution
How It Works:
- Before streaming a track, Llamafin checks for offline copy
- Searches all downloaded containers
- Finds matching track with valid file
- Plays local copy instead of streaming
- Zero network usage
Integrity Checks:
- Only uses files marked as not corrupted
- Verifies file exists on disk
- Checks file accessibility
- Falls back to streaming if local copy invalid
Offline Library Views
When offline, you can still browse:
| View | What's Available |
|---|---|
| Albums | Downloaded albums only |
| Artists | Artists with downloaded content |
| Songs | Downloaded songs |
| Genres | Genres with downloaded songs |
| Playlists | Playlists with downloaded tracks |
| Recently Added | Recently downloaded albums |
| Recently Played | Recently played offline songs |
| Frequently Played | Most-played offline songs |
Offline Search
- Search within downloaded content
- Works completely offline
- Finds artists, albums, songs, playlists
- Instant results (no network needed)
Download Settings
Quality Settings
| Setting | Options | Description |
|---|---|---|
| WiFi Quality | Auto, 96-320 kbps, Max | Download quality on WiFi |
| Cellular Quality | Auto, 96-320 kbps, Max | Download quality on cellular |
| Smart Workers | Auto, Always, Never, Numeric MB | Use background workers |
| Concurrent Chunks | 3-8 | Parallel chunk downloads |
| Chunk Size | 1-10 MB | Size per chunk |
Download Behaviour
| Setting | Options | Description |
|---|---|---|
| Prefer Downloaded Media | Never, WiFi Only, Cellular, Always | Use offline copies when available |
| Cellular Downloads | Enabled/Disabled | Allow downloads on cellular |
| Download Lyrics | Enabled/Disabled | Auto-download lyrics |
| Sonic Analysis | Off, Always, Auto, Post-Completion | When to run audio analysis |
Cache Settings
| Setting | Options | Description |
|---|---|---|
| WiFi Cache Size | Disabled, Next, 100MB-10GB, Unlimited | Cache limit on WiFi |
| Cellular Cache Size | Disabled, Next, 100MB-10GB, Unlimited | Cache limit on cellular |
| WiFi Track Limit | Disabled, 5-100, Unlimited | Max cached tracks on WiFi |
| Cellular Track Limit | Disabled, 5-100, Unlimited | Max cached tracks on cellular |
Download Repair & Recovery
Smart Repair (Repair Download)
What It Does:
- Identifies missing or corrupted files
- Only re-downloads what's needed
- Preserves successfully downloaded files
- Resumes from first missing file
When to Use:
- Download failed partway through
- Some files missing after completion
- Corruption detected in files
- Incomplete download after app crash
Hard Reset (Reset Download)
What It Does:
- Deletes all downloaded files for container
- Clears all progress
- Starts download from scratch
- Re-fetches all metadata
When to Use:
- Smart repair didn't fix issue
- Want to re-download at different quality
- Severely corrupted container
- Starting completely fresh
Refresh & Sync
Refresh:
- Checks server for new tracks
- Adds new tracks to download
- Doesn't remove existing tracks
- Updates metadata
Sync:
- Full bidirectional comparison
- Identifies tracks to add
- Identifies tracks to remove (deleted from server)
- Updates container to match server
Deletion Management
Deleting Downloads
Single Item Deletion:
- Remove individual tracks from container
- Frees up space
- Container remains downloaded
- Can re-download later
Container Deletion:
- Delete entire album/artist/playlist
- Removes all files
- Frees all space
- Can re-download later
Protected Downloads
Playback Protection:
- Cannot delete tracks currently in playback queue
- Protects current track + next/previous tracks
- Prevents playback interruption
- Clear queue first, then delete
Background Deletion
How It Works:
- Queued for background deletion
- Processed in batches when scheduler is idle
- Platform-optimised batch sizes:
- Mobile: 3 items per batch
- Desktop/Web: 10 items per batch
- Retries failed deletions (up to 3 attempts)
Storage Statistics
Download Statistics
Track Metrics:
- Total tracks downloaded
- Total disk space used
- Total playback time
- Per-container breakdown
User vs Cache:
- User Downloads: Content you explicitly downloaded
- Cache Downloads: Automatically cached tracks
- Separate statistics for each
- Independent limits and management
Storage Management
View Storage Usage:
- See space used by each container
- View cache size
- Identify largest downloads
- Track download trends over time
Integrity Validation:
- Runs once at app startup
- Recalculates all statistics from raw data
- Corrects any discrepancies
- Ensures accurate reporting
Error Handling
Download Failures
Automatic Retry:
- Each component retries up to 3 times
- Images: Skipped on failure (non-critical)
- Audio files: Retried (critical)
- Lyrics: Skipped on failure (optional)
- Analysis: Retried later
Failure Notifications:
- Notified when download fails
- Error message explains issue
- Retry button available
- Can repair or reset download
Common Issues
| Issue | Cause | Solution |
|---|---|---|
| Insufficient Storage | Not enough disk space | Free up space, retry |
| Network Error | Connection lost | Check connection, resume |
| Server Error | Jellyfin server issue | Wait and retry |
| Permission Denied | File access blocked | Grant storage permission |
| Corrupted File | Download interrupted | Repair or reset download |
Technical Specifications
| Specification | Value |
|---|---|
| Download Methods | Direct, Transcoded, Concurrent Chunks |
| Concurrent Chunk Limit | 3-8 (configurable) |
| Chunk Size Range | 1-10 MB (configurable) |
| Task Retry Limit | 3 attempts per component |
| Cache Healing Interval | 15 minutes |
| Low Storage Threshold | 500 MB |
| Background Deletion Batch (Mobile) | 3 items |
| Background Deletion Batch (Desktop) | 10 items |
| Cache Crossfade Buffer | 2 tracks |
| Sonic Analysis Corruption Threshold | >5 seconds duration variance |
| Download Queue | Unlimited containers |
| Offline Views | All library views supported |
| Local Match Resolution | Automatic before streaming |
| Storage System | IndexedDB + File System |
| Cache Container ID | llamafin-cache-container |