Integrations

How integrations behave

Every integration except the core catalog is optional, and none of them stops Synthseek from starting. A misconfigured or unreachable service logs a warning and Synthseek boots anyway, then shows that integration as unhealthy in Settings. An unreachable catalog shows under Settings, Maintenance, System status.

Each integration exposes a live status you can see from its settings card.

Plex

Three independent things. Library scans and playlist sync each have a switch, and playing from Plex comes with the connection.

Library scans

After a successful import, Synthseek asks Plex to scan the new file’s folder. The file appears without waiting for Plex’s own schedule.

Playlist sync

Playlists you request or create in Synthseek can be mirrored to Plex.

• Push one playlist, or all eligible playlists at once, from either the requests screen or your library.
• A background job keeps mirrored playlists named correctly and topped up.
• Renames flow both ways.
• Optionally prefix or suffix mirrored playlist names with the owner’s username, so a shared server stays legible.

Sync only adds tracks. The one exception is a playlist kept in sync with its source: a track removed there is removed from the mirrored copy too.

Playing from Plex

Once Plex is connected, Synthseek works out which of your tracks your Plex server also holds. A track Synthseek has no file for then plays from Plex instead, and by default your own copy plays first. When a track is in both places you can switch the playing track to the other copy from the player’s settings. Playing an album or artist asks you where to play it from when your first source is missing some of its tracks.

Each listener can also have their plays counted in Plex. With Plex connected, the Plex row under Connected accounts offers Record my plays in Plex. Their plays, in the web player or in a music app, then count in their own Plex library too, when Plex holds the track.

Why a Plex playlist can show fewer tracks

A mirrored playlist reflects tracks that are complete in Synthseek and were found in Plex. There are three distinct reasons a track can be missing, and they need different responses:

Navidrome and Jellyfin

Synthseek can play a track from Navidrome or Jellyfin when it has no file for it, as it does from Plex. Music apps connected to Synthseek play those tracks too. This starts once you connect the server under Settings, then Media & playback, where Plex is set up too. When more than one server holds a track, Synthseek tries them in the order set on that page. Navidrome finds more of your tracks with Report Real Path turned on for the Synthseek player, and its connection test says when it is off.

Each listener can link their own Navidrome or Jellyfin account under Connected accounts to have their plays counted there. Synthseek does not keep their password.

With playlist sync on for a server, playlists are mirrored to Navidrome or Jellyfin the way they are to Plex, each into the account its owner linked. A playlist imported from a server is never synced back to it.

Lidarr

Lidarr is a delegate target rather than a download source. Handing a request to Lidarr means Lidarr takes it over entirely and manages the download in its own catalog. Synthseek marks the request as delegated and stops working on it.

• Choose Lidarr as the source when making a request.
• Select which tags to apply.
• Choose a monitor scope, from that album only through to the artist’s full discography.

The handoff is validated before anything is created. Synthseek resolves the artist and album in Lidarr’s own catalog first, and if Lidarr cannot manage it, the request is rejected with a clear reason and no rows are created. Lidarr can only manage releases MusicBrainz knows about, so a brand new release cannot be delegated.

Beets

Beets no longer tags or files anything. It is still bundled, and what Synthseek normally runs it for is the presence check behind the Beets CLI row in Settings. One opt-in repair pass, off unless you turn it on, still drives it to resync its own database.

If you are moving an existing Beets library over, Synthseek reads its database once to pick up the MusicBrainz identities Beets had collected. It looks for that database where the Beets configuration at BEETS_CONFIG declares it, so point that at your own configuration to hand the identities over.

AcoustID

AcoustID identifies a recording from the audio itself rather than from its filename or tags. Synthseek uses it for two different things:

1. Verification. Checking that a downloaded file really is the recording you asked for. This is the identity gate described on the Download Engine page.
2. Tagging. Identifying a track so it is tagged as the recording it really is, rather than as whatever the catalog named.

The key is free from acoustid.org. Without it, neither of the above runs, and verification falls back to tag comparison alone.

Metadata providers

The catalog provides the primary picture of a track, album, artist, or playlist. Deezer is the default adapter and needs no key, no account, and no authentication.

Around it sit enrichment providers, each contributing something the catalog does not have:

Enrichment never blocks anything. If a provider is unavailable, the page renders without it and tells you which source is degraded and for how long. A provider that fails repeatedly is stopped being called for a while, then probed once to see whether it has recovered.

Artwork from the catalog, Cover Art Archive, fanart.tv and the Spotify image CDN is served through a proxy on your own instance, with a disk cache. An image a different provider supplies is loaded by your browser directly from that provider.

Library sources

A library source is where your existing collection lives: Spotify, or a connected Plex, Navidrome, or Jellyfin server. Import on the library page lists them.

Each member connects their own. Spotify connects over OAuth, and you can then browse your saved albums, saved tracks, and playlists, select what you want, and import it. A server offers its playlists through the account the member linked under Connected accounts. An imported playlist can be kept in sync so later additions flow through.

The Spotify connection needs a client ID and a public base URL, because the OAuth callback returns over the internet.

Discovery services

ListenBrainz and Last.fm, both per member, both configured under Listening & discovery.

ListenBrainz provides four kinds of mix: collaborative filtering recommendations, weekly exploration, weekly jams, and daily jams. Choose which you want, name them, and decide whether Synthseek should request their tracks automatically. A mix can update a single playlist in place rather than creating a new one each refresh.

Last.fm provides your recent scrobbles and top tracks, and powers similar-artist recommendations across the application.

Listening services

Last.fm and ListenBrainz also take plays the other way, from Synthseek to them. That is a separate per-member connection under Settings, then Listening & discovery, and it is described with the web player in Features. Last.fm needs its shared secret alongside the API key before anyone can connect an account; ListenBrainz needs only the user token from your profile there.