Spotify Connect
Relevant source files
The following files were used as context for generating this wiki page:
Spotify Connect manages device discovery, remote playback mirroring, and device transfer within the Spotty application. It enables the client to control playback on other Spotify-enabled devices and receive state updates from the Spotify playback network.
The system uses a pinned Rust librespot backend as the production owner for sessions and streaming. A Swift-based API layer communicates with Spotify's spclient service to issue commands and fetch track metadata for the Connect queue.
Sources: README.md:21-25, Backend/spotty-playback/src/lib.rs:1-8, Sources/Spotty/Spotify/AGENTS.md:9-12
Architecture and Implementation
Spotty implements Spotify Connect through a hybrid architecture. The Rust backend handles the low-level protocol and session lifecycle, while the Swift layer manages the user interface and high-level command orchestration.
Backend Integration
The Rust bridge links the librespot-connect crate to manage the device's presence in the Spotify Connect cluster. It utilizes Spirc for playback control and ClusterUpdate to handle changes in the device network.
The diagram shows the flow from Swift commands to the Spotify service, which then notifies the Rust backend via the Spotify Connect protocol.
Sources: Backend/spotty-playback/src/lib.rs:36-40, Sources/Spotty/Spotify/SpotifyConnectAPI.swift:233-238
Spotify Connect API
The SpotifyConnectAPI struct manages communication with https://spclient.wg.spotify.com/. It signs requests using Spotify credentials, including access tokens and client tokens, to authorize remote playback commands.
Command Execution
Commands are sent to a specific target device identified by a targetID. The send function constructs a path using the source and target device identifiers.
| Method | Endpoint Path | Description |
|---|---|---|
| POST | connect-state/v1/player/command/from/{sourceID}/to/{targetID} | Dispatches a Connect command to a remote device. |
| GET | metadata/4/track/{gid} | Fetches detailed metadata for a track using its GID. |
Sources: Sources/Spotty/Spotify/SpotifyConnectAPI.swift:222-240, Tests/SpottyBoundaryTests/ConnectMetadataTransportChecks.swift:34-40
Supported Commands
The SpotifyConnectCommand enum defines the available actions that you can perform on a remote device.
| Command Kind | Key in JSON | Action |
|---|---|---|
pause | pause | Suspends playback. |
resume | resume | Continues playback. |
next | skip_next | Advances to the next track. |
previous | skip_prev | Returns to the previous track. |
seek | seek_to | Changes playback position (milliseconds). |
shuffle | set_shuffling_context | Toggles shuffle mode. |
addToQueue | add_to_queue | Appends a track URI to the queue. |
setQueue | set_queue | Replaces the entire upcoming queue. |
Sources: Sources/Spotty/Spotify/SpotifyConnectAPI.swift:23-44, Tests/SpottyBoundaryTests/PlaybackPanelChecks.swift:150-165
Data Structures and Encoding
Command Envelope
Every Connect command is wrapped in an envelope before transmission. This envelope includes a connection_type (defaulting to "wlan") and a unique intent_id generated as a UUID string without hyphens.
private nonisolated struct SpotifyConnectCommandEnvelope: Encodable, Sendable {
let command: SpotifyConnectCommand
let connectionType = "wlan"
let intentID = UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
enum CodingKeys: String, CodingKey {
case command
case connectionType = "connection_type"
case intentID = "intent_id"
}
}
Sources: Sources/Spotty/Spotify/SpotifyConnectAPI.swift:203-213
GID and URI Handling
Spotify Connect identifies tracks using 16-byte Hexadecimal Global IDs (GIDs). The client converts between standard Base62 Spotify URIs and these Hex GIDs for metadata requests.
- URI to GID: The system extracts the Base62 ID from
spotify:track:<ID>and converts it to a 32-character Hex string. - GID to URI: Hex strings received from the API are converted back to Base62 for library and UI identification.
Sources: Sources/Spotty/Spotify/SpotifyConnectAPI.swift:273-311
Metadata Resolution
When a device joins the Connect cluster, it often receives only track URIs. The SpotifyConnectAPI resolves these into displayable metadata including titles, artists, and artwork URLs.
Summary
Spotify Connect in Spotty provides a native macOS interface for controlling the global Spotify playback network. By combining a Rust-based librespot engine for protocol compliance with a Swift-based spclient API for orchestration, the project enables remote playback control, queue management, and metadata synchronization without requiring the official Spotify Web API.
Sources: README.md:12-16, Backend/spotty-playback/src/lib.rs:1-8