Usage Guide

This guide covers day-to-day usage of soundspan: setup, navigation, playback behavior, and administration.

For deployment and installation, see DEPLOYMENT.md. For configuration and security, see CONFIGURATION_AND_SECURITY.md.

First-Time Setup

Create the first account (this user becomes admin)
Optionally configure integrations (see INTEGRATIONS.md)
Wait for initial library scan and enrichment

Moving from another server? Instead of creating an account, select Restore from a backup on the first-run screen and upload a backup from the old server's Admin page. Everything in its database comes back: accounts, settings, playlists, history, and the analyzed library. See BACKUP_AND_RESTORE.md.

Home and Search

Home surfaces continue listening, recently added artists, Made For You mixes, recommendations, popular artists, community playlists, podcasts, and audiobooks
Search includes tabs for library, peers, discovery, Soulseek, and podcasts; peer and Soulseek tabs appear when their integrations are enabled
Search shows one Songs section: your library songs first, then the songs you liked on TIDAL or YouTube Music that are not in your library yet (under From your streaming services), then matches from outside your library (under More songs when the streaming group is shown). External matches carry a provider badge (TIDAL or YouTube) and never repeat a song shown above them.
External songs with a streaming match play right from the results, and every row — owned or not — has the full menu with like/dislike, Go to artist, and Go to album
The From your streaming services group shows up to five songs, each with a provider badge, on the All and My Library tabs. It matches the words of your search (up to six) against the song title, artist, and album, but does not correct typos. Each row's menu has the same add-to-library options as in your Library (see Your Library), and Library → Remote lists all of them
Search also lists the albums of those streaming songs under Albums from your streaming services, below Your Albums: up to six, each with a provider badge, on the All and My Library tabs. It matches the words of your search (up to six) against the album title and artist. An album already in your library is not listed again
Search understands artist and album names, tolerates typos, and ranks near-misses by similarity instead of alphabetically
Discovery search supports preview/download/subscription actions
Explore and /radio station tiles (Quick Start, genres, decades) open a generated station playlist you can inspect before playing; Shuffle All still starts playback immediately
The Vibe Map in the main navigation plots your analyzed library as an explorable similarity map. Laying out the map is slow, so it is built once and kept for about a day; the chip in the bottom-right corner says when it was built and how many songs it covers. Songs analyzed after that build appear on the next one, and the server starts that next build on its own, in the background, once enough new songs have been analyzed (at least 50 and at least a tenth of the map); the current map stays on screen until the fresh one is ready. Very large libraries show a sample of songs (the chip says Sample); the same songs stay on the map from one build to the next, and raising VIBE_MAP_WORKER_MEMORY_MB lets the map hold more of them. A song that is not in the sample still gets a spot when it plays: the map places it next to its closest sampled songs, marks the beacon with a dashed ring, and Find on map flies there. If a newer audio analysis is still running, the chip shows a Re-analyzing badge with how far along it is; the map keeps using the previous results and switches to the new ones automatically once enough songs are done.
Artists and albums you browse are remembered locally. Repeat visits load instantly, and the pages keep working during MusicBrainz outages. Entries untouched for 180 days are cleaned up automatically.

Sharing a song

Every track's menu has Copy link to song. The link opens the album page with that song highlighted and starts playing it. On a brand-new device the browser may ask for one tap before audio starts.

Your Library

The Library page lists your music as Artists, Albums, and Songs.

Where the music comes from

When peer servers or a streaming service are available, buttons above the list choose what to show:

All — everything: the music files on this server, music shared by peer servers, and the songs you liked on TIDAL or YouTube Music that are not in your library yet.
Local — only the music files on this server. Nothing from peers or streaming services ever appears here.
Peers — only music shared by other servers. This button appears when federation is turned on.
Remote — only the songs you liked on TIDAL or YouTube Music that are not in your library yet. This button appears when you are signed in to TIDAL, or when YouTube Music is turned on for this server.

Songs you liked on TIDAL or YouTube Music

When you like a song that plays from TIDAL or YouTube Music, it appears in your Library right away. A small TIDAL or YouTube badge marks it, so you can always tell it apart from your own files, and it plays from that service.

Only your own likes appear. Other people's likes stay in their own Library.
Search finds them too: the songs in their own From your streaming services group below your library songs, and their albums under Albums from your streaming services. Other people's streaming albums never appear in your search.
Artists you only know from streaming appear in Artists with the number of streaming albums or songs you liked. Their artist page lists those albums under Discography together with your own, each with its badge. If MusicBrainz lists an album with the same title, that album still appears under Albums Available or Singles and EPs, so admins can download it, and other users can request it when requests are on. The exception is the MusicBrainz album that soundspan matched your streaming album to: it appears only once, as your streaming album, whose page offers Download or Request.
If you sign out of TIDAL, or an admin turns a service off, its songs leave your Library until it is back. Your likes are kept, and My Liked still lists them.
To take a streaming song out of your Library, unlike it. Streaming songs have no Delete option, because there is no file to delete.
Sorting artists by Most Tracks counts only your own files.
The Library shows up to the 5,000 most recently liked songs from each service.

Adding a streaming song to your library

Open the song's menu (the ⋮ button at the end of the row). What it offers depends on the song's album and on who you are:

When the album has a MusicBrainz match, admins see Add album to library. It downloads the whole album, the same as the Download button on an album page.
When the album has a MusicBrainz match and music requests are turned on, other users see Request album. It asks an admin to add the album (see Requesting Music).
When the album has no MusicBrainz match, admins see Add song to library. It downloads that one song. A TIDAL song needs TIDAL set up as a download source (see TIDAL Downloads).
Otherwise the menu has no add option. This is the case for users who are not admins when the album has no MusicBrainz match, and for admins on a TIDAL song when TIDAL is not set up as a download source.

soundspan looks up MusicBrainz matches for the albums of your liked streaming songs in the background, about once an hour. A song whose album gets a sure match offers Add album to library or Request album, the same as a song on an album with a MusicBrainz match. The streaming album's page offers Download or Request for it too. An album without a sure match is checked again a week later, and a match is checked again after a month.

When your library already has the matched album, for example after you add it, soundspan does not offer that album again:

A liked song that the album did not bring in, such as a streaming-only bonus track, offers neither Add album to library nor Request album. Admins see Add song to library instead, under the same rules as a song whose album has no MusicBrainz match: a TIDAL song needs TIDAL set up as a download source.
The streaming album's page shows no Download or Request.
The streaming album does not appear in the Albums list or on the artist page, so with All the album shows once, as your own copy. Its leftover liked songs stay in Songs and still open the streaming album's page.

After the files arrive and the next library scan matches the song to them, only your own copy shows, without the badge.

Artist Playback Order

Artist-level Play queues owned albums newest-to-oldest, with track ordering by disc and track number.

Podcast Behavior

Playing an older podcast episode creates a forward-only queue of newer episodes; starting the latest episode plays just that episode. If a queue is already active, the episode (and its not-yet-queued newer episodes) is inserted after the current item instead of replacing the queue, so anything you queued stays queued.

Podcast episodes and music tracks share one mixed-media play queue: while an episode plays you can queue tracks behind it (and vice versa) with "Add to queue" / "Play next", and skip controls and auto-advance move through the combined queue. Listen Together sessions remain music-only.

Video podcasts work too. When an episode is published only as a video (MP4, M4V, or WebM), soundspan plays its sound like any other episode; the picture is not shown. If an episode comes in both audio and video versions, soundspan uses the audio version. Video files are much larger than audio files, so these episodes take longer to cache and use more disk space.

Playback Settings

Configure stream/transcode quality and cache behavior in Settings.

Player quality badges show active source details (codec/bitrate or bit depth/sample rate).

Volume Leveling

Volume leveling evens out loudness differences between songs so you do not reach for the volume knob between a quiet 90s master and a modern loud one. It is on by default in Automatic mode: albums played front-to-back keep their intended dynamics, while shuffle, radio, and mixed queues are leveled per song. Set it to By track, By album, or Off under Settings -> Playback -> Volume leveling. Leveling only turns loud songs down and gives quiet songs a small, clip-safe boost; songs the analyzer has not measured yet play unchanged until the background measurement catches up.

Scrobbling

Scrobbling sends the music you play in soundspan to your listening-history service. Each user connects their own accounts under Settings -> Scrobbling. Two services are supported:

ListenBrainz. Copy your user token from listenbrainz.org/settings and paste it into the Connect form. No server setup is needed.
Last.fm. Click Connect Last.fm. A Last.fm page opens asking you to approve the connection. Approve it, come back, and click I've approved — finish connecting. Last.fm requires the server operator to set LASTFM_API_KEY and LASTFM_SHARED_SECRET first; the settings page tells you if they are missing.

Once connected, each service has its own on/off toggle, so you can pause forwarding without disconnecting. Disconnect removes the stored credential.

What gets sent: finished tracks (scrobbles) and now-playing updates, for music you play in the app or through a connected Subsonic client. Scrobbling never delays or blocks playback — if a service is down, deliveries retry in the background and are dropped after repeated failures. If a service rejects your stored credential, the connection is switched off and you are asked to reconnect.

Social and History

Activity panel Social tab lists users who are online and sharing presence.
If a user shares listening activity, their current track appears inline in the Social roster.
Non-admin accounts only see Notifications and Social in the activity panel (Active, History, and Imports remain admin-only).
Open My History from Settings -> History & Personalization (Open My History) for queue-like controls: click-to-play, add to queue, and add to playlist.

Requesting Music

Non-admin users cannot download music directly. Instead, they can ask for it.

Asking for an album

Open an album that is not in the library. A Request button appears where admins see Download. Artist pages and Release Radar offer the same request.
Click Request. The button changes to Requested, and the admins are notified.

Following your request

Open My Requests from the avatar menu, or from the side menu on a phone. Each request shows where it stands:

Status	What it means
`Pending`	No admin has reviewed it yet. You can cancel it.
`Approved`	An admin approved it. The status updates within a few minutes.
`Approved — queued`	An admin approved it. The download waits for its turn.
`Approved — downloading`	The album is downloading now.
`In your library`	The album arrived. `Open album` takes you to it.
`Declined`	An admin said no. Their reason shows on the row when they gave one.
`Failed`	The download did not finish. An admin can retry it or decline it.
`Cancelled`	You cancelled it.

The button on the album page follows along too: Requested, then Approved, then Downloading.

You get a notification when your request is approved, declined, or failed, and when the album is in your library. The library notification opens the album page. A failure notification says whether the download failed or was stopped before it finished.

Reviewing requests (admins)

The Requests entry in the avatar menu shows how many requests are waiting. On the Requests page:

Approve sends the album into the download queue. Decline asks for an optional reason, which the requester sees.
Approve all from <user> approves that user's pending requests, up to 25 at a time. Run it again to approve the rest.
Decline stale declines every pending request older than the age you pick (7, 14, 30, or 90 days), up to 200 at a time, with an optional reason.
A failed request shows Retry and Decline. Retry starts a new download. Admins also get a notification when an approved request fails.
Use the status filter and the page buttons to move through long lists.

A download that starts when an admin approves a request gets only the album that was asked for. It never falls back to a different album by the same artist; when no source has the album, the request fails. If the album is already downloading for another reason when the request is approved, the request follows that download instead.

Limits

You cannot request an album that is already in the library, already requested, or already downloading.
Each user has a daily request cap (default 10). Operators can change it with REQUESTS_PER_USER_PER_DAY.
After an admin declines an album, nobody can request it again for 30 days. If you try too early, the message says when you can ask again. Operators can change the wait with REQUESTS_DENIED_COOLDOWN_DAYS, and 0 turns it off. Declining stale requests does not start this wait.
Operators can turn the whole feature off with FEATURE_REQUESTS=false.

On the default recommendation mode, Discover Weekly playlists generate for everyone from music the server already has and never download albums. The legacy download-based mode is admin-only.

Keyboard Shortcuts

Key	Action
Space	Play / Pause
N	Next track
P	Previous track
S	Toggle shuffle
M	Toggle mute
Arrow Up	Volume up
Arrow Down	Volume down
Arrow Right	Seek forward 10 seconds
Arrow Left	Seek backward 10 seconds

Administration

Admins can manage users, integrations, downloads, enrichment automation, queue dashboards, and API keys.

Common admin areas

User Management
Connected Now live card under User Management for currently connected accounts
Integration and storage settings
Download source/fallback settings
Enrichment controls
Rebuild on the Vibe Map's status chip, which throws away the cached map and builds a fresh one right away instead of waiting for the daily rebuild; the current map stays on screen until the new one is ready
Activity panel events and active jobs
Library Insights panels: metadata gaps, analysis coverage, duplicate clusters, storage breakdown, and low-bitrate albums
Federation health panel with per-peer sync, stream, and error diagnostics
API keys and Swagger docs
Queue dashboard (Bull Board): Open queue dashboard on the Admin page opens it in a new tab. Access lasts 15 minutes; reopen it from the Admin page when it expires, or end it early with End dashboard access. The dashboard cannot be opened by typing its address directly.
API keys: a key created under Settings is sent in an X-API-Key header (not as a Bearer token); the settings page shows an example

Backups

Admin → Backup downloads a backup of everything in the database. Type a passphrase of at least 12 characters twice, then select Download backup. Keep the passphrase: the backup can't be restored without it. Music files are not in the backup. To restore, deploy a fresh soundspan and select Restore from a backup on its first-run screen. BACKUP_AND_RESTORE.md lists what a backup restores and what you lose since the last one.

Album downloads

Album downloads run through a queue. One album downloads at a time across the whole server, and the queue survives restarts — queued albums resume where they left off.

Download all missing albums on an artist page queues each missing album and shows progress as the list is worked through. Promo releases, bootlegs, remix/live/demo/compilation groups, and albums where the artist is only featured are skipped.
A download that delivers only part of an album is reported as Partial download: N/M tracks instead of claiming success.
If the requested album cannot be found on the primary source, the job moves to your configured fallback source or fails with a clear reason. It never substitutes a different release.

Technical admin configuration and security notes are in CONFIGURATION_AND_SECURITY.md.

Sharing libraries between servers (Federation)

Federation lets two soundspan servers share their music libraries. Sharing is read-only: a connected server can browse and stream your library, but it can never change it.

Every connection has two separate roles:

Share my library — you give another server access to your library.
Connect to a library — you get access to another server's library.

Each direction is set up on its own. There is no single "two-way" switch. This is deliberate: each step tells you clearly whether it worked, so a connection can never half-succeed without you knowing.

Both controls live on the Admin page under Federation. Federation must be enabled on both servers. The server that shares its library must be reachable from the other server over HTTPS; for two-way sharing that means both servers need an HTTPS address the other can reach.

Share your library with a friend

Open Admin -> Federation -> Share my library.
Enter a name for the server you are sharing with. Tick the embeddings box if you also want to share the data behind vibe features.
Click Issue credential. The token is shown once — copy it before closing the dialog.
Send the token to the other admin, along with your server's URL. Once they connect, your server shows them under Sharing to them.

Online-status sharing is built into every connection, but it is private by default. A user only appears in the other server's Social tab if they turn on Share online presence in their own Social settings — one switch covers this server and its peers. Remote users always show under a From <server name> heading, so it is clear they are on another instance.

If a token is lost or leaked, use Rotate on that peer's card to issue a fresh one, or Revoke to cut off access.

Connect to a friend's library

Ask the other admin to issue a credential for you and send you the token, plus their server URL.
Open Admin -> Federation -> Connect to a library.
Enter a name for their server, their server URL, and the token.
Click Connect with token. Their library appears in your search and browse surfaces after the first sync.

If the connection fails, the error tells you why: the token was rejected, the server was unreachable, or its certificate failed validation. Each of these has a different fix, so read the message before retrying.

Two-way sharing

Two-way sharing means both servers do both steps:

You issue a credential for them, and connect to their server with the token they issued for you.
The other admin does the same on their side.

That is four steps across the two servers. Each peer's card shows the two directions separately — Sharing to them and Consuming from them — so you can always see exactly which halves are active, offline, or revoked. A peer card without a URL shows No remote URL — they connect to this server: that is a server you share to, so the connection always comes from their side.

Instance display name

By default your server introduces itself to peers using its hostname, which in container deployments can look like soundspan-backend-84975bdf86-h27qt. Set a friendly name in Admin -> Federation -> Instance display name before you issue or accept a credential so the other side sees something readable.

Health and diagnostics

The federation health panel shows per-peer sync freshness, stream usage, and the class of the last failure (unreachable, TLS, authentication, or invalid response). It also shows whether vibe embeddings are federating with each peer; if the peers run different embedding spaces, the panel says so and the fix is upgrading the out-of-date server.

Social sharing between servers (Federation)

If your server is federated with others, two social surfaces can cross between them: online status and public playlists. Sharing follows the same choices you already made for this server — share your presence, or make a playlist public, and it applies to peers too. Nothing extra is shared behind your back, and presence is still off by default.

Seeing friends on other servers. When your server is federated, the Social tab gains sections like "From Family server" listing people on that server who chose to share. Peer status updates every few minutes — the tab shows how fresh each section is. To appear on other servers yourself, turn on Share online presence in Settings -> Social — the same switch that shows you on this server. Your current track travels only if Share listening status is also on.

Playlists from other servers. Public playlists are shared automatically between federated servers — public means public, on this server and its peers. Private playlists never leave your server; make a playlist private to stop sharing it. Peer playlists show up right alongside your own: in the sidebar playlist list and on the Playlists page, each marked with a small badge naming the server it comes from. Use the All / Local / Peers buttons on the Playlists page (or the sidebar's filter menu) to narrow the view, and the "From your peers" section on Home for a quick look. Open one to play it, Follow it (it stays live and updates when the owner changes it), or Save a copy (a snapshot that becomes a normal playlist of yours). Tracks you also have locally play from your library; the rest stream from the peer, and anything the peer can no longer provide is shown dimmed.

When you opt in, the other server sees your username or display name — that is how friends recognize you. What never crosses servers: your listening history, your private playlists, your email, and your login details. Servers only exchange what the people involved explicitly chose to share.