Job Scheduler
Audience: End users, system administrators Last Updated: 2026-04-05 Version: 2.0.0
Overview
The Job Scheduler is Llamafin's background task management system. It handles long-running operations like downloads, library refreshes, sonic analysis batches, and cache maintenance — all without blocking your ability to use the app.
Think of it as a smart queue that processes work in the background, tracks progress, automatically retries failed operations, and persists its state so nothing is lost if you close the app.
What It Does
- Manages Background Operations: Downloads, analysis, cache healing, and cleanup jobs run without interrupting playback or browsing
- Tracks Progress: Real-time progress updates at both job and individual step levels
- Auto-Retries Failed Operations: Uses intelligent retry with increasing delays to handle temporary network issues
- Persists State: Jobs are saved to local storage and restored on app restart
- Handles Failures Gracefully: Non-critical failures (like missing album art) are skipped without stopping the entire job
- Supports Priority: Jobs can be reordered to run important work first
Key Concepts
Jobs and Tasks
The scheduler organises work into a two-level hierarchy:
| Level | Description | Example |
|---|---|---|
| Job | A complete operation, like "Download Album Container" | Contains multiple steps |
| Task | An individual step within a job | Download album art, download audio file, fetch lyrics |
A job progresses through tasks sequentially — task 1 must complete before task 2 begins.
Job Status Lifecycle
Every job moves through these states:
| Status | Description |
|---|---|
| Pending | Queued and waiting for its turn to run |
| Running | Currently being executed |
| Paused | Temporarily stopped (can be resumed) |
| Completed | Finished successfully |
| Failed | Encountered an unrecoverable error |
| Cancelled | Stopped by user action |
| Skipped | A non-critical step was skipped to continue the job |
Job Types
The scheduler handles several categories of work:
| Job Type | Purpose |
|---|---|
| Download Container | Offline downloads of albums, playlists, or individual tracks with all associated assets (audio, images, lyrics, analysis) |
| Sonic Analysis Batch | Bulk audio analysis for fingerprinting, BPM detection, and loudness measurement |
| Cache Healing | Repairs stale or corrupted cache entries |
| Cache Pruning | Removes outdated cached data to free space |
| Cleanup | Background file deletion and filesystem maintenance |
| System Maintenance | General system health operations |
| Refresh Library | Updates library metadata from the server |
Task Types
Individual steps within jobs include:
| Task Type | Purpose |
|---|---|
| Download Image | Fetches album art, artist photos, or backdrops |
| Download Audio | Downloads the actual audio file for offline playback |
| Download Lyrics | Retrieves synchronised or unsynchronized lyrics |
| Fetch Metadata | Gets information about media items |
| Run Plugin Analysis | Executes audio analysis plugins (sonic analysis) |
| Verify Container Integrity | Checks that downloaded files are valid and complete |
| Cleanup Filesystem | Removes temporary or orphaned files |
Configuration
Scheduler settings are found at Settings → Advanced → Scheduler.
Concurrency
Controls how many jobs can run simultaneously:
| Setting | Value | Description |
|---|---|---|
| High Stability | 1 job | Default. One job at a time for maximum reliability |
| Moderate Parallelism | 2 jobs | Two jobs run concurrently |
| Resource Pressure | 3 jobs | Three jobs with warning indicator |
| Experimental | 5 jobs | For development/testing use |
Note: Currently, the scheduler runs only one job at a time regardless of this setting. The concurrency options are prepared for future multi-job support.
Retry Limit
Controls how many times a failed step is retried before the entire job is marked as failed:
| Setting | Retries | Behaviour |
|---|---|---|
| No Retries | 0 | Fails immediately on first error |
| Single Retry | 1 | One retry attempt before failing |
| Default | 3 | Three retries with increasing delays (2s, 4s, 6s = 12s total) |
| Persistent | 5 | Five retries for unreliable connections |
| Maximum | 10 | Ten retries for extremely unstable conditions |
Retries use increasing delays (2 seconds × retry number) to give transient issues time to resolve.
Auto-Clear Completed
When enabled, automatically removes completed jobs from the queue view. This keeps the job list clean and focused on active work.
Default: Disabled (completed jobs remain visible)
Detailed Logging
When enabled, produces verbose logs for all scheduler operations. Useful for troubleshooting but not recommended for normal use due to log volume.
Default: Disabled
How It Works
Queue Processing
The scheduler operates as a continuous loop:
┌─────────────────────────────────────────────────┐
│ Job Queue │
│ │
│ [Pending Job 1] → [Pending Job 2] → [... ] │
│ │
│ ↓ Check: Is scheduler busy? │
│ ↓ Check: Is there a pending job? │
│ │
│ ┌───── No ─────┐ ┌───── Yes ─────┐ │
│ │ Wait for │ │ Start next │ │
│ │ completion │ │ job │ │
│ └───────────────┘ └───────────────┘ │
│ ↓ │
│ Execute tasks sequentially │
│ ↓ │
│ Job complete? │
│ ↓ │
│ ┌──── No ────┐ ┌─── Yes ───┐ │
│ │ Next task │ │ Mark done │ │
│ └────────────┘ └───────────┘ │
│ ↓ │
│ Back to queue check │
└─────────────────────────────────────────────────┘
Job Lifecycle
- Queued: A feature (typically Downloads) creates a job and adds it to the queue with Pending status
- Started: When the scheduler is free, the next pending job begins execution
- Running: Tasks execute one at a time in sequence
- Progress: Each completed task updates the job's overall progress percentage
- Completion: When all tasks finish, the job is marked Complete and the scheduler checks for the next pending job
Retry Behaviour
When a task fails:
- The scheduler checks if retries remain (based on the retry limit setting)
- If retries are available, it waits and tries again (delay increases with each retry: 2s, 4s, 6s...)
- If all retries are exhausted, the entire job is marked as Failed
- Some failures are non-critical (like missing lyrics) — these are skipped rather than failed, allowing the job to continue
Persistence
The scheduler saves its state to local storage:
- Immediate saves: When jobs are added, removed, or cancelled
- Throttled saves: During active job execution (saves at most every 2 seconds to avoid performance impact)
- Startup restore: Jobs are reloaded from storage when the app starts, so interrupted jobs can resume
Job Priority
You can manually reorder jobs in the queue:
- Move to Front: Puts the job at the front of the queue (next to run)
- Move to Back: Puts the job at the end of the queue (last to run)
Integration with Other Features
Downloads System (Primary Consumer)
The Downloads feature creates the majority of scheduler jobs. When you download an album or playlist for offline playback:
- Downloads creates a Download Container job with multiple tasks
- Each task handles a different asset type (audio, images, lyrics, analysis)
- Progress is shown in the downloads view with per-step status
- Failed downloads automatically retry based on your scheduler settings
Sonic Analysis
Background audio analysis jobs are automatically queued by the LlamaSense system when:
- Network conditions are optimal
- The device is idle
- New content has been added
These run as low-priority jobs and won't interfere with downloads or playback.
Cache Management
Cache healing and pruning jobs maintain system health:
- Cache Healing: Scans for and repairs corrupted cache entries
- Cache Pruning: Removes outdated data to free storage space
- Cleanup: Deletes temporary files that are no longer needed
Settings Integration
Your scheduler configuration (concurrency, retry limit, auto-clear, logging) is stored in Advanced Settings and applied immediately when changed.
Error Handling & Reliability
Self-Healing Mechanisms
| Scenario | Behaviour |
|---|---|
| Temporary network failure | Automatic retry with increasing delays (2s, 4s, 6s...) |
| Non-critical task failure | Task is skipped, job continues to next task |
| App restart during job | Job state is restored from local storage |
| Missing server resource | Task is skipped (e.g., album with no lyrics) |
| User cancellation | Job is marked as Cancelled with a clear message |
User Notifications
- Job started: Visible in the debug queue view and downloads panel
- Job completed: Toast notification (if enabled)
- Job failed: Toast notification with error details and retry option
- Progress updates: Real-time progress bars in the queue view
Known Limitations
| Limitation | Impact |
|---|---|
| Single-job execution | Only one job runs at a time, even if concurrency is set higher |
| Auto-clear setting unused | The "auto-clear completed" toggle has no effect currently |
| Detailed logging unused | The "detailed logging" toggle has no effect currently |
| Permanent timestamp changes | Moving a job to front/back permanently alters its creation timestamp |
Technical Specifications
| Specification | Value |
|---|---|
| Job execution model | Sequential (one job at a time) |
| Task execution model | Sequential within a job |
| Default retry count | 3 attempts |
| Retry delay pattern | 2s, 4s, 6s (linear backoff) |
| Total retry time (default) | 12 seconds before job failure |
| Persistence storage | IndexedDB (local browser storage) |
| Persistence save frequency | Immediate for structural changes, 2-second throttle for progress updates |
| Job states | 7 (Pending, Running, Paused, Completed, Failed, Cancelled, Skipped) |
| Job types | 7 categories |
| Task types | 13 types |
| Priority levels | 4 (Low, Normal, High, Critical) |
| Concurrency options | 4 (1, 2, 3, 5 jobs — currently locked to 1) |
Debug Queue View
A debug interface is available at Settings → Advanced → Debugging → Scheduler that shows:
- All jobs in the queue with their current status
- Active tasks within running jobs
- Progress bars for each job and individual task
- Job type, creation time, and error messages
- Controls to cancel, pause, resume, or remove jobs
This view is primarily intended for troubleshooting and monitoring background operations.
Related Documentation
- Download System - Creates most scheduler jobs
- Settings System - Scheduler configuration
- Sonic Analysis - Background analysis jobs
- Offline Support - Offline download workflows
Last Updated: 2026-04-05 Version: 2.0.0