Overview
The Spotify module integrates with the Spotify Web API to provide "Now Playing" overlays and a full dashboard music player. It supports playback control (play, pause, next, previous, seek, volume, shuffle, repeat), queue management, playlist browsing and playback, device selection and transfer, and track search. Spotify credentials are stored encrypted per-account. Access tokens are kept fresh by the centralized Token Refresh Worker — request handlers read a ready-to-use token via oauth::get_fresh_connection_token and never refresh inline. All playback actions are logged as events in TimescaleDB and broadcast via Redis pub/sub for real-time overlay updates. The Now-Playing worker polls adaptively: every 5 seconds while a track is playing and every 30 seconds when paused, idle, or after an error.
Architecture
Backend
- GraphQL (
apps/api/src/graphql/spotify.rs) -- Queries for combined Spotify state and track search. Mutations for playback control, queue management, playlist playback, and device transfer.
- Crate (
crates/lo-spotify-api/src/) -- SpotifyClient wraps the Spotify Web API with methods for now_playing, queue, devices, playlists, search, play, pause, next, previous, seek, volume, shuffle, repeat, add_to_queue, transfer_playback, play_playlist. Its SpotifyClient::refresh_token() is #[deprecated] and reserved for the initial OAuth code exchange, which has no DB row to read yet — internal callers must use oauth::get_fresh_connection_token instead, so refreshes cannot race the Token Refresh Worker.
- Worker (
apps/api/src/workers/spotify.rs) -- Polls the Now-Playing endpoint at PLAYING_POLL_INTERVAL_SECS (5 s) / IDLE_POLL_INTERVAL_SECS (30 s), honours a Retry-After on rate limits, and backs off to the idle interval after 5 consecutive errors.
- Credentials -- Stored in PostgreSQL via
db::spotify::get_spotify_credentials(). Client ID, client secret, access token, and refresh token are all encrypted at rest using crypto::encrypt/decrypt. Connection is managed through the Connections module (Spotify as a platform).
- Event Logging -- Every playback action emits an event (e.g.,
spotify:play, spotify:pause, spotify:skip) to TimescaleDB and broadcasts it via Redis pub/sub asynchronously.
Frontend
- Dashboard music player with now playing display, playback controls, queue view, playlist browser, and device selector.
- Overlay widget displays current track info, album art, and progress bar.
- Next.js API proxy routes call GraphQL internally.
API
GraphQL Queries
Every Spotify query and mutation in apps/api/src/graphql/spotify.rs is gated by
FeatureGuard::new("feature:music").and(PermissionGuard::new(<permission>)); the
REST twins call auth.require_permission(…) + require_feature(…, "feature:music", …).
The three manual-connect operations live in channel_status.rs / routes/channel_status.rs
and carry the permission only — no feature:music gate on either protocol.
| Query | Feature | Permission | Description |
|---|
spotifyState | feature:music | spotify:read | Combined state: now playing, queue, devices, playlists (fetched in parallel via tokio::join!) |
spotifySearch(query, limit?) | feature:music | spotify:read | Search Spotify tracks (default limit: 20) |
spotifyManualStatus | — | spotify:read | Manual-connect status (active, remainingSeconds) |
GraphQL Mutations
| Mutation | Feature | Permission | Description |
|---|
spotifyPlayback(input: SpotifyPlaybackInput!) | feature:music | spotify:playback (+ spotify:volume for the volume action) | Control playback. Actions: play (optional track URI), pause, next, previous, seek (position in ms), volume (0-100), shuffle (bool), repeat (off/context/track). The volume branch performs an inline require_permission(SPOTIFY_VOLUME) check, matching REST. |
spotifyQueue(uri: String!) | feature:music | spotify:queue | Add a track to the Spotify queue |
spotifyTransferPlayback(deviceId: String!) | feature:music | spotify:device | Transfer playback to a different device |
spotifyPlayPlaylist(input: SpotifyPlayPlaylistInput!) | feature:music | spotify:playlist | Start playing a playlist. Input fields: uri plus optional deviceId, name, coverUrl, trackCount, playlistUrl. When deviceId is provided it is forwarded to Spotify as ?device_id= so the target device is activated in the same call (avoids a transfer+play race where Spotify returns "No active Spotify device"). |
spotifyCreatePlaylist(name: String!, public: Boolean) | feature:music | spotify:playlist | Create a new Spotify playlist |
spotifyRenamePlaylist(id, name) | feature:music | spotify:playlist | Rename a Spotify playlist |
spotifyDeletePlaylist(id) | feature:music | spotify:playlist | Delete (unfollow) a Spotify playlist |
spotifyAddToPlaylist(playlistId, trackUris: [String!]!) | feature:music | spotify:playlist | Add tracks to a Spotify playlist |
spotifyRemoveFromPlaylist(playlistId, trackUri) | feature:music | spotify:playlist | Remove a track from a Spotify playlist |
startSpotifyManual | — | spotify:worker | Start manual Spotify connect (30 min TTL). Returns SpotifyManualStatus. |
stopSpotifyManual | — | spotify:worker | Stop manual Spotify connect. Returns Boolean. |
REST Endpoints
All paths live under /v1/spotify. Bodies are snake_case.
| Method | Path | Permission | Description |
|---|
GET | /v1/spotify/state | spotify:read | Combined now-playing / queue / devices / playlists state |
POST | /v1/spotify/playback | spotify:playback | Playback control: play, pause, next, previous, skip_to, seek, volume, shuffle, repeat. The volume action additionally requires spotify:volume |
GET | /v1/spotify/queue | spotify:read | Current Spotify queue |
POST | /v1/spotify/queue | spotify:queue | Add a track URI to the queue |
GET | /v1/spotify/devices | spotify:read | List available playback devices |
POST | /v1/spotify/devices | spotify:device | Transfer playback to a device |
GET | /v1/spotify/playlists | spotify:read | List user playlists |
POST | /v1/spotify/playlists | spotify:playlist | Start playing a playlist |
GET | /v1/spotify/search | spotify:read | Search Spotify tracks (query, optional limit) |
GET | /v1/spotify/manual-connect | spotify:read | Manual-connect status (+ remaining seconds) |
POST | /v1/spotify/manual-connect | spotify:worker | Start manual Spotify polling (30 min TTL) |
DELETE | /v1/spotify/manual-connect | spotify:worker | Stop manual Spotify polling |
The five playlist-management mutations (spotifyCreatePlaylist,
spotifyRenamePlaylist, spotifyDeletePlaylist, spotifyAddToPlaylist,
spotifyRemoveFromPlaylist) have no REST twin — POST /v1/spotify/playlists
only starts playlist playback. Use GraphQL for playlist management.
WebSocket
| Channel | Gate | Feature |
|---|
spotify:{account_id} | spotify:read | none at the WebSocket layer |
channel_gate_for("spotify") maps the channel to ChannelGate::Permission("spotify:read")
and channel_feature_for returns None for it, so the plan check happens on the
REST/GraphQL paths rather than at subscribe time. The channel has no entry in
channel_broadcast_permission_for, so clients cannot broadcast on it — playback
state is published server-side by the Spotify worker only.
Event Types Generated
| Event Type | Trigger |
|---|
spotify:play | Play action |
spotify:pause | Pause action |
spotify:skip | Next or skip_to action |
spotify:previous | Previous action |
spotify:seek | Seek action |
spotify:volume | Volume change (includes old/new volume) |
spotify:shuffle | Shuffle toggle |
spotify:repeat | Repeat mode change |
spotify:queue_add | Track added to queue |
spotify:device | Playback transferred to different device |
spotify:playlist | Playlist started playing |
Permissions
| Permission | Description |
|---|
spotify:read | Read now playing state, queue, devices, playlists, search tracks |
spotify:playback | Control playback (play, pause, next, previous, seek, shuffle, repeat) |
spotify:volume | Change playback volume (gates the volume slider in the dashboard and popout player) |
spotify:queue | Add tracks to the queue |
spotify:playlist | Manage and play playlists |
spotify:device | Transfer playback to another device |
spotify:worker | Start/stop the manual Spotify polling worker |
Database
Spotify uses the Connections module tables for credential/token storage:
| Table | Database | Description |
|---|
app_credentials | PostgreSQL | Encrypted client_id and client_secret per platform per account |
channel_connections | PostgreSQL | Encrypted access_token, refresh_token, expires_at, platform_channel_id, scopes |
Events generated by Spotify actions are stored in:
| Table | Database | Description |
|---|
platform_events | TimescaleDB | Spotify events (spotify:play, spotify:skip, etc.) with enriched raw JSON containing track info and triggering user |
Data Flow
- User connects Spotify via the Connections module (OAuth flow).
build_client_from_ctx() loads the account's Spotify credentials and calls oauth::get_fresh_connection_token for a decrypted, already-fresh access token. It performs no refresh of its own.- User performs a playback action (e.g., skip) via the dashboard.
- The
SpotifyClient method is called against the Spotify Web API.
- The action is enriched with current track data and triggering user info.
- An event is asynchronously inserted into TimescaleDB and broadcast via Redis pub/sub.
- Overlay "Now Playing" widget receives the event via WebSocket and updates the display.
Key Files
| Path | Description |
|---|
apps/api/src/graphql/spotify.rs | GraphQL queries and playback/playlist mutations |
apps/api/src/graphql/channel_status.rs | spotifyManualStatus, startSpotifyManual, stopSpotifyManual |
apps/api/src/routes/spotify.rs | REST handlers under /v1/spotify |
apps/api/src/routes/channel_status.rs | REST handlers for /v1/spotify/manual-connect |
apps/api/src/workers/spotify.rs | Adaptive Now-Playing polling worker |
crates/lo-spotify-api/src/ | Spotify Web API client |
apps/api/src/db/spotify.rs | Credential retrieval helpers |
apps/api/src/crypto.rs | Token encryption/decryption |
apps/api/src/oauth.rs | Token refresh persistence |