Queue Management
Relevant source files
The following files were used as context for generating this wiki page:
Queue Management handles the synchronization, presentation, and mutation of the Spotify playback queue. The system coordinates data from multiple sources, including Spotify Connect and the Spotify Web API, to provide a unified view of upcoming tracks and recently played history.
The architecture relies on QueueService to manage authoritative state and PlaybackStore to handle user-initiated actions like adding or removing tracks. It enforces strict precedence rules where complete Connect occurrence order takes priority over Web API entry lists to ensure identity stability across devices.
Sources: Sources/Spotty/Spotify/QueueService.swift:23-27, Sources/Spotty/Spotify/PlaybackStore+Queue.swift:12-16
Core Components and Architecture
The queue system is divided into domain models that define the data structure and services that manage network and state transitions.
Key Data Structures
| Type | Description |
|---|---|
QueueEntry | A selectable row in the UI with a stable identity based on its URI and occurrence index. |
ProvenanceQueueSnapshot | A non-isolated snapshot containing the account epoch, revision, and source of the queue data. |
QueueProtocolTrack | Represents a single track in the Connect protocol, including metadata and restriction flags. |
QueueMutationSnapshot | Stores the authoritative state required to perform queue modifications like track removals. |
Sources: Sources/SpottyDomain/PlaybackPanelModels.swift:221-227, Sources/Spotty/Spotify/QueueService.swift:7-16, Sources/SpottyDomain/QueueMutation.swift:5-29, Sources/SpottyDomain/QueueMutation.swift:45-64
Queue Service and Coordination
QueueService acts as the primary actor for fetching and merging queue data. It manages WebCapability to track if the Web API is available or rate-limited. When a Web API request fails with a 429 error, the service enters a 5-minute cooldown period and falls back to Spotify Connect data.
The diagram shows the decision logic used by QueueService to select between Web API and Connect data sources.
Sources: Sources/Spotty/Spotify/QueueService.swift:101-110, Sources/Spotty/Spotify/QueueService.swift:207-224, Sources/Spotty/Spotify/QueueService.swift:233-238
Data Synchronization and Merging
The system merges snapshots from different sources to enrich metadata while preserving the authoritative Connect ordering.
- Precedence: Connect order always wins over same-context Web API lists.
- Identity Persistence: When Web API metadata arrives, the system attempts to preserve the Connect
uidfor tracks at matching indices. - Hydration: If a Connect snapshot lacks metadata, the service initiates a background hydration process using
TrackMetadataService, bounded to 8 concurrent requests.
Sources: Sources/Spotty/Spotify/QueueService.swift:23-45, Sources/Spotty/Spotify/QueueService.swift:260-270
Metadata Hydration Flow
This diagram illustrates how missing track details are fetched in batches without blocking the initial queue presentation.
Sources: Sources/Spotty/Spotify/QueueService.swift:257-295
Queue Mutations
Mutations include appending tracks and removing selected upcoming occurrences.
Adding to Queue
Tracks are appended using the add_to_queue command. Multiple URIs are sent sequentially in visible order. This process is independent of the transport state to prevent quick sequential additions from being dropped.
Sources: Sources/Spotty/Spotify/PlaybackStore+Queue.swift:24-34
Removing from Queue
Removals are strictly validated against a QueueMutationPolicy. The system refuses removals under several conditions:
- Playback is owned locally (Mac), as local replacement is currently unsupported.
- The selection includes the "Now Playing" track or history.
- The queue snapshot is provisional or incomplete.
- The account or engine epoch has advanced since the selection was made.
Sources: Sources/SpottyDomain/QueueMutation.swift:244-278, Sources/SpottyDomain/QueueMutation.swift:192-198
This flowchart describes the validation steps required before a removal command is transmitted to Spotify.
Sources: Sources/SpottyDomain/QueueMutation.swift:250-280, Sources/Spotty/Spotify/PlaybackStore+Queue.swift:76-85
UI Integration
The SidePanelView provides the user interface for the queue and history. It uses a SidePanelQueueRefreshIdentity to determine when a refresh is necessary based on connection status and track changes.
// Sources/Spotty/Views/SidePanelView.swift:15-19
struct SidePanelQueueRefreshIdentity: Equatable {
let isConnected: Bool
let currentTrackURI: String
let connectOrderingVersion: UInt64
}
The view supports:
- Context Menus: Provides "Play" and "Remove from Queue" actions for selected tracks.
- Keyboard Commands: Supports native Delete/Backspace keys for removing upcoming occurrences.
- Section Headers: Dynamically labels tracks as "Next in queue", "Recommended" (autoplay), or "Next up" based on the entry provider.
Sources: Sources/Spotty/Views/SidePanelView.swift:145-170, Sources/Spotty/Views/SidePanelView.swift:186-190
Summary
Queue Management in Spotty ensures a reliable cross-device playback experience by treating Spotify Connect as the authoritative source of truth for ordering. By strictly validating mutations and using the Web API primarily for metadata enrichment, the system maintains stable track identities even during complex multi-device session handoffs.
Sources: Sources/Spotty/Spotify/QueueService.swift:23-30, Sources/SpottyDomain/QueueMutation.swift:244-249