Skip to main content

Playback Queue & Player Management

Audience: End users and technical evaluators Last Updated: 2026-04-04 Version: 2.0.0

Overview​

Llamafin's player system manages playback queues, shuffle and repeat modes, multi-device playback targets, and provides intelligent features like auto-resume, gapless playback, and continuous autoplay.

Queue Management​

Building Your Queue​

Multiple ways to start listening:

ActionWhat It Does
Play AlbumLoads all tracks from the album into queue
Play ArtistLoads all songs from the artist
Play PlaylistLoads your curated playlist
Play GenreLoads all songs matching the genre
Play StudioLoads all albums from the record label/studio
Play SongSingle song playback (can add more later)
Play All DownloadsAll your offline content
Play All From LibraryEntire music library (up to 500 tracks)

Queue Structure​

Your playback queue contains:

  • Full Track Metadata: Title, artist, album, artwork, duration, play counts
  • Original Position Tracking: Remembers where each track came from
  • Local File References: Points to downloaded copies when available
  • Play Statistics: Times played, last played date
  • Sonic Analysis Data: Audio fingerprints for similarity matching

Queue Operations​

OperationDescription
Play NextInsert tracks immediately after current track
Add to QueueAppend tracks to the end of the queue
Clear QueueStop playback and remove all tracks
Stop & ClearGraceful shutdown (closes player UI first)

Shuffle Mode​

Smart Shuffle Algorithm​

Llamafin implements an intelligent shuffle that respects your listening history:

How It Works:

  1. Turning Shuffle ON:

    • Identifies your current position in the queue
    • Preserves all tracks you've already heard (history)
    • Randomly shuffles only the upcoming tracks
    • You won't hear recently played tracks again

  2. Turning Shuffle OFF:

    • Restores the original order perfectly
    • Uses original position tracking to rebuild sequence
    • Returns to exactly how the album/playlist was ordered

Example:

Original Queue:  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
Currently at:    [1, 2, 3] ←  (playing track 3)

Shuffle ON:      [1, 2, 3 | 7, 4, 9, 5, 10, 6, 8]
                 ↑ History preserved ↑ Upcoming shuffled

Shuffle OFF:     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
                 ← Original order restored

Benefits:

  • No duplicate listening in current session
  • Easy return to original order
  • Works with any queue size (minimum 2 tracks)
  • Persists across app restarts

Repeat Modes​

Three distinct repeat behaviors:

Repeat Off (Default)​

Behaviour:

  • Plays through queue normally
  • Pauses when last track ends
  • Rewinds to start of last track (position 0:00)
  • Ready for manual selection

Best For:

  • Intentional listening sessions
  • Working through albums in order
  • Following curated playlists

Repeat One​

Behaviour:

  • Replays current track indefinitely
  • Doesn't advance to next track
  • Manual intervention required to stop

Best For:

  • Learning lyrics or musical parts
  • Focusing on a single song
  • Background ambiance

Repeat All​

Behaviour:

  • When last track ends, wraps to first track
  • Continuous loop through entire queue
  • Seamless transition (no pause at boundary)
  • Shuffle and repeat work together

Best For:

  • All-day background music
  • Parties and events
  • Shuffle + repeat for infinite variety

Playback Controls​

Standard Controls​

ControlFunction
PlayResume paused playback
PausePause at current position
StopStop and clear queue
Next TrackSkip to next track in queue
Previous TrackGo back or restart current track
SeekJump to any position in track

Previous Track Smart Behaviour​

The previous button works intelligently:

If more than 5 seconds into track:

  • Restarts current track from beginning
  • Standard music player behaviour
  • Quick access to track start

If less than 5 seconds into track:

  • Goes to previous track in queue
  • In shuffle mode: restarts current (previous is undefined)
  • At queue start: restarts current track

Advanced Controls​

ControlRangeFunction
Volume0% to 100%Master playback volume
Mute ToggleOn/OffQuick silence without losing volume setting
Seek Bar0:00 to track endScrub to any position

Track Previews​

Quick Audition System​

Sample any track before committing to full playback:

Preview Features:

  • 30-Second Duration: Enough to judge the track
  • Isolated Playback: Doesn't affect your queue or current session
  • Separate Audio Stream: Uses dedicated preview stream
  • Visual Countdown: Shows remaining preview time
  • Early Stop: Cancel preview anytime

Use Cases:

  • Browse albums quickly
  • Verify track before downloading
  • Discover new music efficiently
  • Avoid queue interruptions

Multi-Device Playback​

Playback Targets​

Llamafin can play music on different devices:

TargetDescription
LocalPlay on current device (default)
Jellyfin SessionRemote control another Jellyfin client
Llamafin ConnectControl another Llamafin device directly

Seamless Target Switching​

All controls work regardless of target:

  • Play/Pause/Stop: Routed to correct device
  • Volume Control: Adjusted on target device
  • Next/Previous: Queue management on target
  • Seek: Position control on target
  • Queue Operations: Managed locally, executed remotely

Unified Display​

The player interface shows unified information:

  • Current track (local or remote)
  • Queue contents (synchronised)
  • Playback progress (real-time)
  • Volume level (target device)

Queue Persistence​

Automatic State Saving​

Your playback session is automatically preserved:

What Gets Saved:

  • Complete playback queue (all tracks)
  • Current track and position
  • Shuffle mode status
  • Repeat mode setting
  • Playback target selection
  • Autoplay queue flag

When It's Saved:

  • Queue changes (new playlist, add/remove tracks)
  • Track changes (next, previous)
  • Mode changes (shuffle, repeat toggle)
  • Target changes (switch playback device)

Session Restoration​

When you reopen Llamafin:

  1. Stored State Loaded: Queue, modes, target restored
  2. Current Track Restored: Your last track selected
  3. Autoplay Check: If enabled, playback resumes automatically
  4. Manual Start: If autoplay off, press play to continue

Benefits:

  • Never lose your place
  • Resume listening instantly
  • Perfect for commutes or work sessions
  • Cross-restart persistence

Adjacent Track Preloading​

Intelligent Buffering​

Llamafin prepares upcoming tracks before you need them:

How It Works:

  1. When you start playing a track, the system identifies:
    • Next track in queue
    • Previous track in queue
  2. Both tracks are preloaded into the audio engine
  3. Next track is ready for instant playback
  4. Previous track cached for immediate skip-back

Benefits:

  • Zero Delay: Next track starts instantly
  • Smooth Experience: No loading pauses between tracks
  • Instant Navigation: Skip forward/back immediately
  • Gapless Playback: Seamless transitions enabled

Debounced Processing​

Preloading is optimised:

  • 250ms delay prevents excessive loading during rapid skips
  • Only processes when all dependencies available (settings, network, user)
  • Validates track data before preloading
  • Graceful handling of missing tracks

Autoplay & Continuous Playback​

Smart Queue Extension​

Never run out of music automatically:

Detection:

  • Monitors remaining tracks in queue
  • Triggers when 5 or fewer tracks remain
  • Checks if DJ mode is active

Priority System:

  1. Single-Artist Queue:

    • Detects if all tracks share same album artist
    • Finds next/previous album from same artist
    • Loads album tracks into queue
    • Maintains artist context

  2. Mixed-Artist Queue:

    • Falls back to DJ mode
    • Generates tracks based on current song
    • Uses sonic similarity or smart algorithms
    • Extends queue seamlessly

Album Autoplay:

  • Sorts artist's albums by year and name
  • Selects next album (configurable direction)
  • Wraps around at end of discography
  • Loads tracks maintaining album order

DJ Mode Fallback:

  • If album autoplay fails or not applicable
  • DJ generates tracks similar to current
  • Uses audio fingerprinting
  • Infinite music generation

Voice Search Playback​

Speak to Play​

Voice-activated music selection:

How It Works:

  1. Speak your request ("Play rock music" or "Play Beatles")
  2. Llamafin searches your library
  3. Results analyzed in priority order:
    • Priority 1: Songs (offline first, then online)
    • Priority 2: Albums
    • Priority 3: Artists
    • Priority 4: Playlists
  4. Best match starts playing immediately

Benefits:

  • Hands-free music selection
  • Quick access while driving
  • Natural language queries
  • Offline results prioritised

Self-Healing Playback​

Automatic Error Recovery​

Llamafin fixes problems without interrupting your music:

Missing Local File Detection:

  • Track marked as downloaded but file is gone
  • Happens if you delete downloads while in queue
  • Detected when audio engine tries to play

Automatic Recovery:

  1. Strips stale local file references
  2. Re-fetches track metadata from server
  3. Updates queue with fresh data
  4. Retries playback as remote stream
  5. Notifies you of recovery

Graceful Degradation:

  • If recovery fails completely
  • For playback: informs you and advances to next track
  • For preloading: fails silently (no interruption)
  • Queue remains intact, playback continues

Download Deletion Handling​

When you delete a download that's in the queue:

  • Local file reference cleared immediately
  • Track marked as needing remote stream
  • Next playback fetches from server
  • No errors or interruptions
  • Queue position preserved

Rolling Cache System​

Smart Download Window​

Automatic management of offline content around your current position:

How It Works:

  • Maintains a window of downloaded tracks around current playback
  • Downloads upcoming tracks before you reach them
  • Removes old downloads behind you to save space
  • Configurable cache size (WiFi and cellular separate)

Cache Window:

[Old Downloads] [Current Track] [Future Downloads]
      ↓                ↓                ↓
   Delete Zone      Playing Now      Addition Zone

Configurable Settings:

  • Next Track Only: Cache just 1 upcoming track
  • Numeric Limit: Cache N tracks ahead (e.g., 5, 10, 20)
  • Unlimited: Cache entire remaining queue

Network Awareness:

  • Respects cellular download settings
  • Different limits for WiFi vs cellular
  • Won't download on cellular if disabled
  • Guards prevent excessive data usage

Repeat All Support:

  • When approaching end of queue
  • Wraps around to cache tracks from beginning
  • Maintains full cache window even at queue end
  • Seamless looping with offline content

Proactive Caching​

Predictive Downloads​

Llamafin anticipates your needs:

When Queue is Set:

  • Analyses entire queue for missing downloads
  • Calculates lookahead window based on settings
  • Filters out tracks already downloaded
  • Queues items for background download

Multiple Triggers:

  1. Queue Change: When you modify the queue
  2. Track Change: When advancing to next track
  3. Periodic Check: Every 30 seconds during playback

Guard Clauses:

  • Caching must be enabled in settings
  • Respects prefer_downloaded_media setting
  • Checks cellular permissions
  • Skips if all items already cached

Benefits:

  • Seamless offline playback
  • No manual download management
  • Intelligent use of storage space
  • Always prepared for network loss

Integration with Audio Engine​

Clean Separation of Concerns​

Player and Audio Engine work together:

Player Responsibilities:

  • Queue management
  • Shuffle and repeat logic
  • Track selection and ordering
  • Multi-device targeting
  • State persistence

Audio Engine Responsibilities:

  • Actual audio playback
  • Web Audio API processing
  • Stream management
  • Gapless transitions
  • Visualisation data

Communication Flow​

Player → Audio Engine:

  • "Play this track" (requestPlayback)
  • "Pause/Resume/Stop"
  • "Seek to position"
  • "Set volume"
  • "Preload these adjacent tracks"

Audio Engine → Player:

  • "Playback started" (sync state)
  • "Playback ended" (trigger next track)
  • "Buffering status" (update UI)
  • "Error occurred" (handle recovery)

synchronisation​

When audio engine starts playing:

  1. Player validates track is in queue
  2. Updates current track reference if needed
  3. Preserves rich metadata (sonic analysis, etc.)
  4. Does NOT re-trigger playback pipeline
  5. Records offline playback statistics

Error Handling​

Loading Errors​

Empty Playlists:

  • Detected before queue is set
  • User notified with clear message
  • Queue remains unchanged
  • Loading state cleared

Missing User ID:

  • Validated before API calls
  • Prevents failed requests
  • Informs user of authentication issue
  • Suggests re-login

Network Failures:

  • Retry logic for transient errors
  • Graceful degradation to offline mode
  • User notified of persistent failures
  • Queue preserved for retry

Playback Errors​

Stream Failures:

  • Self-healing attempts recovery
  • Falls back to remote stream if local missing
  • Advances to next track if unrecoverable
  • Maintains queue integrity

Device Errors:

  • Audio context suspension handled
  • Autoplay policy compliance
  • User gesture requirements communicated
  • Pending play requests retry automatically

Technical Specifications​

SpecificationValue
Queue Size LimitNone (limited by memory)
Shuffle AlgorithmFisher-Yates (Knuth)
Repeat Modes3 (off, one, all)
Previous Track Threshold5 seconds
Preload Debounce250ms
Rolling Cache Debounce (track)100ms
Rolling Cache Debounce (queue)150ms
Periodic Cache CheckEvery 30 seconds
Crossfade Buffer2 tracks
Autoplay Trigger Threshold≤ 5 tracks remaining
Library Play All Limit500 tracks
Storage Keyscurrent_item, shuffle_status, repeat_status, playback_target
Playback Targetslocal, Jellyfin session, Connect peer