System Started
Dashboard initialized successfully
Recently Added
The newest movies & shows in your library.
Loading…
Video Dashboard
Monitor your video library and downloads
TMDB Enrichment
Status: Idle
No active matches
Progress: 0 / 0
TVDB Enrichment
Status: Idle
No active matches
Progress: 0 / 0
OMDb Ratings
Status: Idle
No active matches
Progress: 0 / 0
YouTube Dates
Status: Idle
No channels queued
Progress: 0 / 0
fanart.tv Artwork
Status: Idle
No active matches
Progress: 0 / 0
OpenSubtitles
Status: Idle
No active matches
Progress: 0 / 0
YouTube Votes
Status: Idle
No active matches
Progress: 0 / 0
SponsorBlock
Status: Idle
No active matches
Progress: 0 / 0
DeArrow
Status: Idle
No active matches
Progress: 0 / 0
Trakt
Status: Idle
No active matches
Progress: 0 / 0
TVmaze
Status: Idle
No active matches
Progress: 0 / 0
AniList
Status: Idle
No active matches
Progress: 0 / 0
Wikidata
Status: Idle
No active matches
Progress: 0 / 0
System Stats
Live performance metrics.
Active Downloads
0
Currently downloading
Finished Downloads
0
Completed this session
Download Speed
0 KB/s
Combined speed
Disk Usage
--
Video library size
System Uptime
0m
Application runtime
Memory Usage
--
Current usage
Library
Your collection at a glance.
Library
Movies, shows & episodes
0
Movies
0
Shows
0
Episodes
--
Disk Size
Upcoming
Airing today for the shows you follow. Open calendar →
Loading…
Quick Actions
Jump straight into the video side.
Studios
Poster overlays & smart collections — built from your library's metadata.
Library
Movies and shows from your media server
0
Movies
Search
Movies, TV shows & people — everything stays in-app
🎞
Search SoulSync
Find any movie, show or person. Owned titles open your library detail; the rest open a live preview — no external links.
Across Discover
🌐
📺 Your streaming services
pick what you subscribe to — adds an “On your streaming services” rail to your feed
Browse the full catalog
This Week
Upcoming episodes from your shows
Watchlist
Shows and people you follow
Wishlist
Movies & episodes you want to grab
Import
Downloads that need a hand — place them by hand or dismiss
Downloads
No downloads yet. Hit Grab on a search result and it'll show up here.
Automations
Video tasks that keep your movie & TV library fresh — separate from the music side
—
Fetching the full episode list from TMDB… missing episodes will fill in shortly.
Playlists
Cast & Crew
Details
Videos
Photos
Review
Where to Watch
Collection
More Like This
—
Cast & Crew
Details
Videos
Photos
Review
Where to Watch
Collection
More Like This
Tools
Maintenance jobs and library tools
Library Maintenance
Jobs that scan your video library and report findings for review
Loading jobs...
Studios
🎨 Overlay Studio
Design poster overlays (ratings, resolution, awards…) in a visual editor and apply them to your whole library — filtered targeting, nightly re-apply, clean-art restore.
🗂️ Collection Studio
Build living collections — charts, franchises, universes, seasonal windows, smart rules — with generated posters, server sync, and wishlist tie-ins.
Database & Scanning
Library Scan
Last Scan: Never
Movies:
0
Shows:
0
Episodes:
0
Size:
0.0 MB
Idle
0 movies, 0 shows
Server Scan
Tell the media server to scan its folders for newly-downloaded movies & episodes — then a Library Scan pulls them into SoulSync.
Idle
Issues
Problems reported on library items
Loading issues…
Loading…
Photos
Known For
Filmography
Loading…
Studio
Films
No films found.
Music Dashboard
Monitor your music system health and manage operations
Service Status
Connection health for every service SoulSync uses.
Metadata Source
●
Disconnected
Response: --
Media Server
●
Disconnected
Response: --
Download Source
●
Disconnected
Response: --
System Stats
Live performance metrics.
Active Downloads
0
Currently downloading
Finished Downloads
0
Completed this session
Download Speed
0 KB/s
Combined speed
Active Syncs
0
Playlists syncing
System Uptime
0m
Application runtime
Memory Usage
--
Current usage
Library
Your collection at a glance.
Library
Checking status...
Recent Syncs
Playlists you've synced.
Quick Actions
Three control rooms inside SoulSync.
Recent Activity
What just happened.
Now
Enrichment Services
API rate monitoring across providers.
Playlist Sync
Synchronize your Spotify, Tidal, and YouTube playlists with your media server
Your Spotify Playlists
Click 'Refresh' to load your Spotify playlists.
Your Tidal Playlists
Click 'Refresh' to load your Tidal playlists.
Your Deezer Playlists
Click 'Refresh' to load your Deezer playlists.
Your Qobuz Playlists
Click 'Refresh' to load your Qobuz playlists.
Paste a Deezer playlist URL above to get started.
Parsed YouTube playlists will appear here.
Paste a Spotify playlist or album URL above to load tracks without needing Spotify API credentials.
Paste an iTunes or Apple Music album/track URL above to load tracks.
My Beatport Playlists
Your created Beatport playlists will appear here.
🏆 Top 10 Lists
Current trending tracks from Beatport charts
🎵 Beatport Top 10
Most popular tracks on Beatport
🎵 Loading Beatport Top 10...
Fetching trending tracks
🔥 Hype Top 10
Editor's hottest trending picks
🔥 Loading Hype Top 10...
Fetching editor's picks
💿 Top 10 Releases
Most popular albums and EPs on Beatport
💿 Loading Top 10 Releases...
Fetching trending albums and EPs
🆕 New Releases
Latest albums and EPs from Beatport
🔥 Hype Picks
Editor selected trending tracks from Beatport
🔥 Featured Charts
Top chart collections from Beatport creators
🎧 DJ Charts
Curated charts from top DJs and artists
Import Playlist from File
Drop your file here
or click to browse
Supported: CSV, TSV, TXT, M3U, M3U8
CSV / TSV
First row as headers (e.g. Title, Artist, Album). Columns are auto-detected or can be mapped manually.
TXT
One track per line (e.g. Artist - Title). Format and separator can be adjusted after upload.
M3U / M3U8
Standard playlist files. Artist, title and duration are read automatically from #EXTINF lines (or the file name for simple playlists).
SoulSync Discovery Playlists
Click 'Refresh' to load your personalized SoulSync Discovery playlists.
Your Last.fm Radio Playlists
Click 'Refresh' to load your Last.fm Radio playlists. Generate new ones from the Discover page.
Your ListenBrainz Playlists
Click 'Refresh' to load your ListenBrainz playlists.
Mirrored Playlists
Playlists you parse from any service will appear here as persistent backups.
Server Playlists
Playlists from your media server will load automatically.
Search
Find artists, albums, and tracks from any metadata source
Enter a search term to get started.
Search Results
Search results will appear here when you select an album or track.
Automations
Configure scheduled tasks and automated workflows
Downloads
No downloads yet. Start one from Search, Sync, Discover, or Library.
Batches
Music Library
Browse your complete music collection
0
Artists
🎵
Artist Name
Albums
0/0
EPs
0/0
Singles
0/0
Show
Include
Status
View
Albums
0 owned
0 missing
EPs
0 owned
0 missing
Singles
0 owned
0 missing
Similar Artists
Discover artists with a similar sound
Artist Map
Explore the connections between your artists
Watchlist
Your watched artists and their similar connections
Genres
Artists clustered by genre across your library and cache
Explorer
Pick any artist and explore outward through their connections
Artist Web
Your library as an interactive similarity graph
Taste Map
Every artist in your library, wired together by similarity
Communities
Your library's real scenes, found from who sounds alike — not genre tags
Discovery Web
Artists you don't have yet, mapped from the ones you do
Adventurousness
Balanced
Safe — artists you already like
Adventurous — deep cuts
Recent Releases
New music from artists you follow
Loading recent releases...
Fresh Tape
New drops from recent releases
Loading fresh tape...
The Archives
Curated from your collection
Loading the archives...
Build a Playlist ?
Create a custom playlist from your favorite artists
How it works:
- Search and select 1-5 seed artists you like
- Hit Generate — the app finds similar artists, pulls their albums, and picks tracks at random
- You get a fresh 50-track playlist mixing your picks with new discoveries
Tip: The more seed artists you add, the more varied the playlist will be.
Seed Artists
0 / 5
Search above to add seed artists
🧠 ListenBrainz Playlists
Playlists from ListenBrainz
Loading playlists...
Year Mixes
Jump into the sound of a decade — open one to see the tracks
Playlist Explorer
Select a playlist above, then explore
Settings
API Configuration
Metadata Source
Where artist, album, and track metadata comes from:
• Spotify — official Spotify; connect your account in the Spotify section below.
• Spotify (no auth) — the same Spotify catalog with no account needed. It's unofficial and best-effort (may break if Spotify changes its site) and can't read your personal library or playlists.
• Deezer / iTunes — free, no account.
• MusicBrainz — free, but limited to 1 request/sec.
• Discogs — needs a personal access token.
• JioSaavn — opt in under Advanced → Experimental. Strong for Indian and Bollywood catalogs.
Tip: if you pick Spotify (no auth) and later connect a real Spotify account, it uses the official account normally and only falls back to no-auth while Spotify is rate-limited — then switches back automatically.
• Spotify — official Spotify; connect your account in the Spotify section below.
• Spotify (no auth) — the same Spotify catalog with no account needed. It's unofficial and best-effort (may break if Spotify changes its site) and can't read your personal library or playlists.
• Deezer / iTunes — free, no account.
• MusicBrainz — free, but limited to 1 request/sec.
• Discogs — needs a personal access token.
• JioSaavn — opt in under Advanced → Experimental. Strong for Indian and Bollywood catalogs.
Tip: if you pick Spotify (no auth) and later connect a real Spotify account, it uses the official account normally and only falls back to no-auth while Spotify is rate-limited — then switches back automatically.
Spotify
›Current Redirect URI:
http://127.0.0.1:8888/callback
Add this URL to your Spotify app's 'Redirect URIs' in
the Spotify Developer Dashboard
Runs the background metadata enrichment worker on the no-auth Spotify source instead of this connected account — keeping bulk enrichment off your official API quota (and dodging rate-limit bans), so your account is reserved for interactive search and playlist sync. On by default. Turn off to enrich through your connected account instead. Works even with no account connected. Note: the no-auth source can't supply artist genres.
iTunes / Apple Music
›Sets the primary Apple Music storefront. Region-specific albums are auto-searched across other storefronts as fallback.
Deezer (Favorites & Playlists)
›Current Redirect URI:
http://127.0.0.1:8008/deezer/callback
Add this URL to your Deezer app at developers.deezer.com
Or use an ARL token for playlist access and downloads (no OAuth app needed):
Log into deezer.com
→ DevTools (F12) → Application → Cookies → copy the
arl value. Provides playlist access + downloads.Discogs
›Get your free token from Discogs Developer Settings
Click "Generate new token" — no app registration needed. Provides 60 req/min and cover art in search results.
Tidal (Playlists & Metadata)
›Current Redirect URI:
http://127.0.0.1:8889/tidal/callback
Add this URL to your Tidal app configuration
Qobuz (Metadata & Enrichment)
›
Connects Qobuz for metadata enrichment (ISRC, labels, copyright). Also used for downloads if Qobuz is your download source.
Alternative: Auth Token — If email/password login fails (CAPTCHA), paste your token directly:
To get your token: log into play.qobuz.com
→ DevTools (F12) → Network tab → find any request to
www.qobuz.com/api.json
→ look in the request headers for X-User-Auth-Token → copy that value.Last.fm
›Get your API key and secret from Last.fm API Account
API key: used for metadata enrichment. API secret: required for scrobbling.
Genius
›Get your token from Genius API Clients
Generate a "Client Access Token" — no OAuth flow needed.
AcoustID Verification
›
Verifies downloaded audio matches expected track using fingerprints
Get your free API key from AcoustID Applications
The fpcalc fingerprint tool is automatically downloaded if needed.
Failed verifications move files to Quarantine folder.
ListenBrainz
›Get your token from ListenBrainz Settings
Self-hosted? Enter your server URL (e.g. http://localhost:8093)
Hydrabase
›P2P metadata network. When enabled and connected, replaces Spotify/iTunes as the primary metadata source for searches.
API Configuration
TMDB & TVDB are required. The video side matches, enriches and automates everything from these — library matching, artwork, airing shows, collections — so nothing works until both keys are set. Both are free. OMDb and fanart.tv below are optional extras.
TMDB
Required ›Get your free key from TMDB API Settings
Required. Primary movie & TV metadata source — nothing on the video side works without it.
TVDB
Required ›Get your key from TheTVDB API
Required. TV series metadata — episodes & air dates the airing automations rely on.
OMDb (Ratings)
›Get a free key from OMDb API
IMDb / Rotten Tomatoes / Metacritic ratings.
fanart.tv (Artwork)
›Get a free key from fanart.tv
Clear logos, clearart, banners, posters & backgrounds (gap-fills missing art).
OpenSubtitles (Subtitles)
›Get a free key from OpenSubtitles (register a consumer)
Records which subtitle languages exist per title.
Trakt (Audience Rating)
›Create a free API app at trakt.tv and paste its Client ID.
Adds Trakt's community audience score (and vote count) to movies & shows — and lets the Collection Studio build collections from public Trakt lists.
MDBList (List Collections)
›Free key from mdblist.com (Preferences → API Access).
Lets the Collection Studio build collections from MDBList lists — the real IMDb Top 250, award lists (Oscar winners), and thousands of community lists.
Community Data (No Key)
›Free community APIs — no key needed. Gap-fill extra data on your library in the background.
YouTube Extras (No Key)
›Free community APIs — no key needed. Enrich cached YouTube videos in the background.
Server Connection
Pick the server the video side uses. Fields are pre-filled from your Music settings — edit them to point video at a different server without touching Music.
Which libraries the video side scans.
📁 Library Organization
Variables: $title, $titlefirst, $year, $quality (e.g. Bluray-1080p), $resolution, $source, $codec, $edition, $tmdbid, $imdbid. Folders split on "/", the last segment is the filename.
Example:
…
Variables: $series, $season (01), $seasonraw (1), $episode (01), $episodetitle, $year, $quality, $resolution, $source, $codec, $tvdbid.
Example:
…
Followed YouTube channels organize as a TV show. Variables: $channel, $year, $sxe (s2024e0315 — lets Plex/Jellyfin index episodes without an online agent), $date (2024-03-15), $month (03), $day (15), $title, $videoid.
Plex tip: set the YouTube library's agent to Personal Media Shows — episode titles then come straight from the filename, and the channel folder gets its poster/fanart automatically.
Example:
…
Following a channel backfills its most recent N videos, then watches for anything new posted after you follow. This is also the rolling "keep the last N current" net the channel scan uses. 0 = don't backfill anything, only grab new uploads going forward. It never pulls the whole back catalog.
How a finished download moves from the download folder into your library.
Tag by the file's real resolution and reject corrupt / sample files. Needs ffmpeg; falls back to the release name when absent.
Deletes the old file when an upgrade lands.
Bring sibling .srt / .ass files alongside the video, renamed to match.
Download the full artwork set — poster.jpg, fanart.jpg, clearlogo.png (plus season posters for shows) — next to the movie / into the show folder. Off by default; Plex/Jellyfin usually fetch their own once the folder is named cleanly. Turn on to pin specific art or for offline/local-assets setups.
Write Kodi/Jellyfin-style movie.nfo / tvshow.nfo (title, plot, rating, genres, cast, ids) so the library is fully portable. Off by default — Plex ignores these, but Jellyfin/Kodi/Emby use them.
Fetch external .srt files from OpenSubtitles next to the video (uses your OpenSubtitles API key on the enrichment settings). Off by default — the free tier is daily-quota-limited, and most releases already carry embedded subs.
Comma-separated language codes to fetch, in priority order (e.g.
en,es). One .srt per language is written as <video>.<lang>.srt.
Upgrade-replaced copies, retention-cleaned YouTube episodes and dismissed imports move into an
ss_recycle folder inside the library instead of being deleted — a safety net if something gets replaced by mistake.
Recycled files older than this are removed for good (cleaned automatically as new files are recycled).
Set a single folder to collect everything (keep it on the same drive as your libraries so moves are instant). Blank = an
ss_recycle folder per library.
New grabs are refused (and the wishlist drains pause) when the target drive has less free space than this — so a download can never fill the disk. 0 disables the check.
Uses the community SponsorBlock database at download time. Mark adds skippable chapters (sponsor, self-promo, intro, outro); Cut removes sponsor/self-promo/interaction segments from the file entirely.
Embeds YouTube's subtitles (your Subtitle Languages above) into the downloaded file so Plex/Jellyfin offer them without sidecar files.
Restores the Radarr/Sonarr standard layout.
Video Preferences
Detail Pages
›Plays a muted trailer behind the hero after a moment (uses more bandwidth).
Server Connections
Video Download Folders
One shared download folder (where slskd / torrent drop files), then a separate library folder per type — finished files are sorted to the right one automatically. SEPARATE from your Music paths.
Where downloads land — point this at the same folder as your slskd / torrent client. This is the SAME folder as the Music side; changing it here changes it there too.
Download Source
Video downloads from slskd, torrent or usenet only. Hybrid tries each enabled source in order.
▼
Quality
Ladder, cutoff, rejects & tie-breakers
One profile for every video source (slskd · torrent · usenet). Quality is read from the release name — pick the ladder you'll accept, where to stop upgrading, what to reject outright, then the soft tie-breakers.
Quality ladder toggle what you'll accept · rank best→worst with the arrows
Upgrade until once you have this resolution (or better) stop chasing upgrades
Never grab hard rejects — skipped no matter what else matches
Preferences soft tie-breakers — they rank candidates, they never reject on their own
Codec
HDR
Audio
Max size skip anything bigger — set per type so a movie and an episode aren't judged the same
Movie No limit
TV episode No limit
▼
YouTube Quality
Resolution ceiling, codec & container for followed channels
A separate, simpler profile for the channels you follow — YouTube is grabbed with yt-dlp, so it's just a resolution ceiling, a codec preference and a container.
Max resolution the most yt-dlp will grab — it steps down to the next available below this
Preferences codec is a soft preference; container is the final muxed file
Codec
Container
▼
Source Settings
Source, stream & concurrency
Choose where to download music from. Hybrid mode tries primary source first,
then falls back to secondary if it fails.
Where to stream audio when previewing tracks. YouTube is instant and requires no setup.
"Active Download Source" uses your configured source (Tidal, Qobuz, etc.) — if that's Soulseek, YouTube is used automatically.
Maximum simultaneous downloads per batch. Soulseek album downloads always use 1 worker
due to per-user upload limits. Higher values speed up large playlists and wishlists.
Checks every selected source & configured connection.
▼
Quality
Profile Format priorities, bitrate, bit depth
How it works: Each download source is checked against this list
top-down. The first target a source can satisfy wins; a source that meets no target
is skipped for the next one (source priority still decides between sources that can).
For lossless, bit depth + sample rate decide the match. For MP3/AAC the bitrate is a
minimum threshold (≥), so VBR and mono files aren't falsely rejected. After
download the real file is verified against the same list. With fallback off, a track
is left missing rather than accepting a quality below every target.
Note: the Downsample hi-res option (under Lossy Copy) also bypasses this gate — if off-list files keep slipping through with fallback off, check that setting too.
Note: the Downsample hi-res option (under Lossy Copy) also bypasses this gate — if off-list files keep slipping through with fallback off, check that setting too.
Any accepted target stops upgrade findings as soon as a file matches any target in the list.
Selected target or better keeps the Quality Upgrade job proposing replacements until the file reaches the selected rank.
Selected target or better keeps the Quality Upgrade job proposing replacements until the file reaches the selected rank.
Source priority goes through your sources in order and
downloads from the first one that has the track. Fastest, fewest
lookups.
Best quality asks every source, then downloads the highest-quality copy it found — even if a faster source also had a lower-quality one. Slower and more API calls, but you never settle for a worse file when a better one exists.
Either way, the per-source retry limits stay the same.
Best quality asks every source, then downloads the highest-quality copy it found — even if a faster source also had a lower-quality one. Slower and more API calls, but you never settle for a worse file when a better one exists.
Either way, the per-source retry limits stay the same.
A single source often returns several copies of the same track.
Off (default): the most likely-correct / fastest copy is downloaded first — the original behaviour.
On: the highest-quality copy (per your target list above) is downloaded first instead; correctness and speed only break ties.
Nothing is skipped and the source order doesn't change, so a track can't go missing — it just prefers the better copy. (This is always how Best quality works, which is why this option only appears for Source priority.)
Off (default): the most likely-correct / fastest copy is downloaded first — the original behaviour.
On: the highest-quality copy (per your target list above) is downloaded first instead; correctness and speed only break ties.
Nothing is skipped and the source order doesn't change, so a track can't go missing — it just prefers the better copy. (This is always how Best quality works, which is why this option only appears for Source priority.)
This does not mean "walk down my list" — the list already
does that on its own.
When on, a file that matches none of your targets (e.g. a 16-bit FLAC or an MP3 when you only listed 24-bit) is accepted anyway as a last resort.
Turn it off to strictly enforce your list — anything off-list is then quarantined instead of completed.
When on, a file that matches none of your targets (e.g. a 16-bit FLAC or an MP3 when you only listed 24-bit) is accepted anyway as a last resort.
Turn it off to strictly enforce your list — anything off-list is then quarantined instead of completed.
▼
Quality on Import
Profile Apply the profile to manually imported files
When importing from Staging, if a track already exists in your library at a lower quality
(e.g. MP3), it will be replaced with the higher quality version (e.g. FLAC).
If disabled, existing tracks are always kept and the import file is skipped.
Note: imported files are always checked against your Quality Profile's priority list above — there's no separate on/off switch for that, since an empty list (or Fallback turned on) already means "accept anything."
Note: imported files are always checked against your Quality Profile's priority list above — there's no separate on/off switch for that, since an empty list (or Fallback turned on) already means "accept anything."
▼
Post-Download Conversion
Profile Downsample hi-res, make lossy copiesWhen a 24-bit or high sample-rate FLAC is downloaded, it is automatically converted to 16-bit/44.1kHz. The hi-res original is replaced, not kept alongside. Requires ffmpeg.
After downloading a FLAC, a lossy copy at the selected codec and bitrate is created in the same folder. Requires ffmpeg.
▼
Audio Verification
Profile AcoustID identity match + truncated/silent detection
Applies to both imports and downloads. When
on, a track that AcoustID runs but cannot confirm
(no fingerprint match / cross-script metadata — the ⚠ "unverified" case) is
quarantined instead of being allowed into the library. Downloads then
try the next candidate; imports just quarantine (no candidate to retry). Only a clean
AcoustID pass is kept.
⚠️ Use with care. AcoustID "could not confirm" is common for perfectly good tracks — anything not in its fingerprint database: new/obscure releases, classical, remixes, live cuts, remasters, non-Latin-script titles. With this on, all of those get quarantined, so you may end up with many legitimate files to review and approve by hand. Nothing is lost (quarantined files can be approved), but expect manual cleanup. Leave this off to keep the safer default: unconfirmed tracks import with the ⚠ "unverified" badge so you can review them without anything being blocked. Transient lookup errors (rate-limit / outage) always import, so an AcoustID outage never stalls you. Requires AcoustID enabled.
⚠️ Use with care. AcoustID "could not confirm" is common for perfectly good tracks — anything not in its fingerprint database: new/obscure releases, classical, remixes, live cuts, remasters, non-Latin-script titles. With this on, all of those get quarantined, so you may end up with many legitimate files to review and approve by hand. Nothing is lost (quarantined files can be approved), but expect manual cleanup. Leave this off to keep the safer default: unconfirmed tracks import with the ⚠ "unverified" badge so you can review them without anything being blocked. Transient lookup errors (rate-limit / outage) always import, so an AcoustID outage never stalls you. Requires AcoustID enabled.
Decodes every downloaded file with ffmpeg to catch fake 30s previews padded to full length and mostly-silent files — the kind whose header lies about the length so mutagen can't catch them. Off by default: this fully decodes each file, the most CPU-heavy post-processing step. Most sources (HiFi, Qobuz) already catch previews on their own, so only turn this on if you see padded/silent files slip through. Applies to all download sources.
Quality Profiles
Click a profile's name to view/edit its settings on the left (this alone never activates it). Per row: ● set as the active default, ✏ rename, ✎ save the settings shown on the left into this profile, ⇩ use for Auto-Import instead of the default, × delete. "Manage" above shows what's active for what.
💡 Filesystem access — easiest setup ▾
▼
Indexers
Prowlarr — search aggregator⬢ Prowlarr
Prowlarr manages your Usenet and torrent indexers and exposes them through one API. SoulSync uses Prowlarr to search across every indexer at once for the Torrent and Usenet download sources.
Don't have it? Grab Prowlarr from
Don't have it? Grab Prowlarr from
prowlarr.com (or your *arr stack). You point Prowlarr at your indexers, then point SoulSync at Prowlarr.
Full URL to your Prowlarr instance (e.g.
http://192.168.1.100:9696).
Found in Prowlarr → Settings → General → Security → API Key.
Comma-separated Prowlarr indexer IDs. Leave blank to search every enabled indexer. Restrict when you have a private tracker you want to prioritise or a noisy public one to exclude.
Connect to Prowlarr and click Refresh Indexer List to see the indexers SoulSync can search.
▼
Torrent Client
qBittorrent · Transmission · Deluge⬢ Torrent Downloader
Where SoulSync sends torrents once Prowlarr finds them. Pick the client you already use — only one can be active at a time. Add the URL of the client's WebUI, log in if it asks for credentials, and hit Test Connection.
qBittorrent: WebUI port (default 8080). Transmission: RPC port (default 9091). Deluge: WebUI port (default 8112). Aria2: RPC port (default 6800) — leave Username blank and put your
--rpc-secret in the Password field.
qBittorrent and Transmission use username + password. Deluge uses password only — paste it in the password field below.
SoulSync tags every torrent it adds with this label so it's easy to spot in your client. Deluge needs the Label plugin installed for this to stick.
Override where the torrent client writes downloads. This path is on the torrent client's machine, not SoulSync's.
Where SoulSync can read finished torrents — its own in-container path. Set this when your client saves to a category folder (e.g. a "Music" category at
/data/downloads/music) that's mounted here at a different path. SoulSync finds the release by name under this folder. Blank = use the Soulseek download/transfer folders.
Give up on a torrent that makes zero download progress for this long — a dead magnet stuck on "downloading metadata", or a swarm with no seeders. Without this, a dud torrent ties up a download slot for the full 6-hour limit. 0 disables (wait the full limit).
Abandon frees the slot so the next source can try. Pause keeps the torrent in your client so you can inspect or resume it manually.
▼
Usenet Client
SABnzbd · NZBGet⬢ Usenet Downloader
Where SoulSync sends NZBs once Prowlarr finds them. Pick one usenet downloader. SABnzbd uses an API key for auth; NZBGet uses a username + password.
SABnzbd: default WebUI port 8080. NZBGet: default WebUI port 6789.
SABnzbd → Config → General → API Key. Used by SABnzbd only.
SoulSync tags every NZB with this category so it ends up in a predictable post-processing folder.
Where SoulSync can read finished NZB downloads — its own in-container path. Set this when SABnzbd/NZBGet writes that category to a folder (e.g.
/data/downloads/music) mounted here at a different path. SoulSync finds the release by name under this folder. Blank = use the Soulseek download/transfer folders.
▼
Retry Logic
What happens when a download is rejectedControls what happens when a downloaded file is rejected (AcoustID mismatch, wrong version, or duration/integrity failure) — independent of post-processing. When on, SoulSync automatically tries the next-best candidate instead of failing the track. Off = quarantine and fail immediately.
Give every source (Soulseek, then HiFi/Tidal/…) its own retry budget. Each source spends queries × retries-per-query attempts before the track moves on. Worst case across two sources can mean many downloads — use for hard-to-match tracks (e.g. CJK artist names). Requires the option above.
When retries are fully exhausted and every candidate for a track failed the same version mismatch (e.g. only an instrumental exists), accept the best (first-tried) one instead of leaving the track missing. Only AcoustID is bypassed — integrity/duration/bit-depth checks still run, so truncated or genuinely wrong files are never let through. Off = leave such tracks failed.
▼
Album Publishing
When album downloads appear in your libraryOff by default — with this off, tracks appear in your library as they finish downloading (unchanged behavior). When on, the tracks of an album download are staged privately and only moved into your media library once the whole album completes, so Plex/Jellyfin/Navidrome never shows a half-loaded album while it's still downloading. If a batch stalls or fails, its tracks stay in staging (never your library) and the failed tracks remain retryable in your wishlist. Only affects full-album and wishlist-album downloads — single tracks and album top-ups (completeness fills) are unaffected.
▼
Paths & Organization
Folders, file templates & library pathsFolder Paths
Container-internal paths. Only change them if you know what you're doing — wrong values break downloads.
Where Organize by playlist builds playlist folders — as shortcuts into your library, so songs are never stored twice. Keep this outside your music library folder so your media server doesn't scan the same tracks twice.
Symlinks use almost no space. Copies are self-contained. Symlinks fall back to copies automatically where the filesystem can't link (Windows without privileges, some network shares, FAT/exFAT drives).
Optional prefix added to every track path in exported M3U files. Use this when your media server needs absolute paths (e.g.
/mnt/music).
File Organization
Variables:
$albumartist, $artist, $artistletter, $album, $albumtype, $title, $track, $disc (01), $discnum (1), $cdnum (CD01 on multi-disc, empty on single), $year, $quality (filename only). Use ${var} to append text: ${albumtype}s → Albums
Variables:
$albumartist, $artist, $artistletter, $title, $track (01), $album, $albumtype, $year, $quality (filename only). Use ${var} to append text: ${albumtype}s → Singles
Renames the files inside each "Organize by Playlist" folder (your real library files are never touched). Filename only — no folders. Variables:
$position (playlist order), $artist, $album, $track, $title. Must include $title and cannot contain "/". Example: $position - $artist - $title → 01 - Daft Punk - One More Time.flac. Empty = keep the original library filename.
Variables:
$artist, $artistletter, $title, $year. Use ${var} to append text. Default: $artist/$title-video
Label used for auto-created disc subfolders on multi-disc albums.
How
$albumartist resolves for albums with multiple artists. "First Listed" uses only the primary artist for folder names (e.g., "Larry June" instead of "Larry June, Curren$y & The Alchemist"). Full artist list is always preserved in file metadata tags.
Separator between multiple artists in the ARTIST tag (e.g.
& matches MusicBrainz/Picard style)
Write each artist as a separate tag value for Navidrome/Jellyfin multi-artist support
Keep only primary artist in ARTIST tag, append others as (feat. ...) in title
When enabled, the same song can be added to the wishlist from different albums (e.g., completing a discography where albums share tracks). When disabled, tracks with the same name and artist are skipped.
Restores original path structure. Your downloads will be organized like before.
Music Library Paths
Tell SoulSync where your music files live. Required for tag writing, streaming, and file detection
when your media server stores files at a different path than SoulSync can see.
Docker users: mount your music folder(s) into the SoulSync container with read-write access,
then add the container-side path here (e.g.
/music).
▼
Post-Processing
Metadata, tags, conversion, lyrics
Master toggle — disabling this skips all metadata, artwork, and lyrics processing.
Core Features
Higher resolution but quality may vary. When off, uses Spotify/iTunes/Deezer art (consistent 640x640). Ignored when a preferred album art source list is set below — add Cover Art Archive to that list instead.
Order the sources to choose whose cover art is used. The first source that has a cover wins; misses fall through to the next, and if none match, your download's own art is kept. Only sources you're connected to are shown — leave all off to keep current behavior.
When a track matches a single release, look up the album that contains it and tag it as that album — so every song in an album gets the same (album) cover instead of some getting the single's art. Off by default: adds an extra metadata lookup per single-matched track.
Analyzes loudness and writes ReplayGain track gain/peak tags. Requires ffmpeg. Adds a few seconds per track.
Maximum drift between the file's actual length and the metadata source's expected length before the file is quarantined. 0 = auto (3s normal, 5s for tracks >10min). Raise this if tracks routinely quarantine for being a few seconds off (live recordings, alternate masterings, etc). Capped at 60s.
Tag Embedding
Toggle a service to enable/disable all its tags, or expand to control individual tags.
▶
3 tags
▶
3 tags
▶
18 tags
▶
4 tags
▶
4 tags
▶
5 tags
▶
5 tags
▶
2 tags
▶
2 tags
▶
5 tags
▶
2 tags
MP3, FLAC, MP4/M4A, OGG
▼
Listening Stats
Play history from your media server
Polls your active media server (Plex, Jellyfin, or Navidrome) for play history
and displays stats on the Stats page.
▼
Discovery
How adventurous your recommendations are
▼
Security & Access
PIN · user accounts · reverse proxy
By default, anyone who can reach SoulSync on your network can use it. Protect access below with a simple shared PIN, or full user accounts with passwords — you only need one. The last group is just for exposing SoulSync over the internet.
🔑 Lock with a PIN simple · one shared PIN
A lock screen appears on every page load, verified against the admin PIN. Closing the tab requires re-entry.
👤 User accounts (login) per-person · best for public access
Everyone signs in with their account name + password. Turning this on replaces the PIN and the profile picker. Set passwords for other people in Manage Profiles.
So you can reset a forgotten password by answering it on the sign-in screen.
Replaces the profile picker + PIN with a sign-in screen. Best for instances exposed to the internet.
🌐 Reverse proxy & remote access
Only needed if you expose SoulSync to the internet behind nginx / Caddy / Traefik. See
Support/REVERSE-PROXY.md.
Trusts the proxy's
X-Forwarded-* headers, marks the session cookie HTTPS-only, and adds security headers. Leave OFF for direct / LAN access over http:// — it would otherwise break plain-HTTP login. Takes effect after a restart.
If an auth proxy (Authelia / Authentik / oauth2-proxy) logs users in in front of SoulSync, enter the header it sets and SoulSync trusts it. Only set this behind a proxy that strips any client-supplied copy of the header. Blank = off.
Origins (full URL, no trailing slash) allowed to open WebSocket connections — one per line or comma-separated. Empty = same-origin only (the secure default; fine for direct access and most reverse-proxy setups). Add your public domain if live updates fail behind a proxy.
* on its own line allows any origin (insecure).
▼
Discovery Pool Settings
Lookback & hemisphere
Controls how far back to scan when adding new artists or refreshing discovery
pool.
Once scanned, artists are kept updated with new releases only.
Adjusts seasonal playlists on the Discover page to match your region.
Southern hemisphere flips seasons (e.g. December = Summer, June = Winter).
Holidays like Christmas and Halloween stay calendar-fixed.
UI Appearance
Audio-reactive visualizer on the sidebar edge when music is playing
Animated particle effects behind each page. Off by default — enable for the eye candy (uses GPU).
Dashboard header buttons animate as floating orbs. Hover the header to expand. Desktop only.
Disables backdrop blur and shadows (the GPU-heavy bits). Keeps functional motion like loading spinners. Good for low-end devices.
Nuclear low-power mode for software-rendered / no-GPU setups (e.g. Docker, remote desktop). Turns off Worker Orbs, Particles, all blur/shadows AND every animation & transition (loading spinners go static). Overrides the three options above.
▼
Database Settings
ConcurrencyNumber of parallel threads for database updates. Higher values = faster updates but more server load.
▼
Database Maintenance
Size, vacuum & cleanup
Loading...
Loading...
Loading...
Compact Database rewrites the entire DB to reclaim unused space. Locks the database briefly — may take a minute on large databases.
Incremental Vacuum enables automatic page reclamation. Requires a one-time full compact to activate. After that, freed pages are reclaimed in small batches automatically.
Incremental Vacuum enables automatic page reclamation. Requires a one-time full compact to activate. After that, freed pages are reclaimed in small batches automatically.
▼
Import
Folder-artist override, permanent library
On by default (legacy behaviour). When enabled, files staged as
Artist/Album/… (or Artist/Albums/Album/…) take the top
folder as the album artist — handy for mixtapes/compilations whose embedded tags
carry DJ names. Turn this off if you drop a mixed pile of songs
under one container folder: otherwise every file's artist gets overwritten with
that folder's name (the cause of the "soulsync" mass-mislabel). With it off, the
metadata-identified artist is always kept.
Off by default. Turn this on if your Transfer folder is your
real, permanent library (served by Navidrome/Plex/etc.) rather than a scratch
drop area. A Deep Scan then never relocates files it doesn't recognize out to
Staging — it leaves them in place and just reports them. Even with this off, a
Deep Scan now refuses to move files when the database looks badly out of sync
with disk, as a safety guard against wiping a library (issue #904).
▼
Filtering
Explicit content & genre whitelist
When disabled, tracks marked as explicit on Spotify will be skipped
during matched downloads. Does not affect manual Soulseek searches.
When picking between Soulseek results, files marked Explicit/Uncensored
rank higher and Clean/Censored/Radio-Edit files rank lower. Nothing is
ever skipped — if only a clean version exists, it still downloads.
Requires explicit content to be allowed.
When enabled, only genres on the whitelist below are kept during enrichment. Junk tags (artist names, radio shows, playlist names) are silently dropped. When disabled, all genres pass through unchanged.
▼
Playlists
M3U export & server playlist sync
Saves an M3U playlist file alongside your music. Albums are skipped — they're already grouped by your media server.
Keeps a single
soulsync_library.m3u of your entire library, rewritten after every scan (deep, incremental, or full refresh) so it stays in sync with the database.
Where the whole-library M3U is written. Leave empty to use your Transfer folder.
"Replace" deletes and recreates the server playlist every sync, which wipes its custom image/description. "Reconcile" updates the same playlist in place (adds new tracks, removes ones no longer in the source) so your custom image and description survive. "Append" only ever adds.
▼
Logging
Log level & path
Controls the level of detail in application logs. DEBUG shows all details, INFO
shows general operations, WARNING and ERROR show only issues.
logs/app.log
▼
SoulSync API
REST keys & inbound endpointREST API Keys
Generate API keys to access SoulSync remotely via the
/api/v1/ endpoints.
Keys are shown once at creation — store them securely.
Loading...
Inbound Request Endpoint
Trigger music downloads from external tools (Discord bots, Home Assistant, curl, etc.)
using any API key above.
curl -X POST http://<host>:8008/api/v1/request \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"query": "Artist - Track Name"}'
Returns a
request_id for status polling. Add "notify_url" to POST results to a webhook on completion.
Also triggers any Webhook Received automations in the Automation Hub.
▼
Developer Mode
Advanced log viewerInactive
Experimental — proceed with caution
▼
Experimental
Opt-in preview featuresFeatures in this section are optional, may change without notice, and are not held to the same support standard as core metadata sources.
Exposes JioSaavn as a primary metadata source on the Connections tab and in search. Free, no account — strong for Indian and Bollywood catalogs; limited to 1 request/sec via the public proxy API. Off by default.
Adds Bandcamp as a Discover search source and a track/album metadata enrichment source (tags, label, credits). Free, no account — uses Bandcamp's own public search and release-page endpoints (unofficial, no guaranteed uptime or rate limits). Off by default.
Initializing log viewer...
0 lines
● Live
Hydrabase
Disconnected
API Calls
Tracks
Albums
Artists
Discography
Album Tracks
Response
API responses will appear here
Network
Peers: --Source Comparisons
When Hydrabase is the active metadata source, searches are compared against Spotify and iTunes in the background.
No comparisons yet. Search with Hydrabase active to generate comparisons.
Tools & Operations
Database management, library scanning, metadata, backups
Library Maintenance
Automated scanning, detection, and repair of library issues
Loading jobs...
Database & Scanning
Database Updater
Last Full Refresh: Never
Artists:
0
Albums:
0
Tracks:
0
Size:
0.0 MB
Idle
0 / 0 artists (0.0%)
Import IDs from File Tags
Read provider IDs (Spotify, MusicBrainz, iTunes, Deezer…) already embedded in your files and fill them into the database — lets enrichment workers skip redundant API lookups. Only fills blanks; never overwrites an existing match.
IDs Filled:
0
Rows Updated:
0
Conflicts:
0
Unreadable:
0
Ready to scan
0 / 0 files scanned (0.0%)
Duplicate Cleaner
Detect and remove duplicate tracks in output folder
Files Scanned:
0
Duplicates Found:
0
Deleted:
0
Space Freed:
0 MB
Ready to scan
0 files scanned (0.0%)
Metadata & Cache
Metadata Updater
Current Artist: Not running
0 / 0 artists (0.0%)
Discovery Pool
View and fix matched/failed discovery results across all mirrored playlists
Matched:
—
Failed:
—
Manual Library Match
Map wishlist and playlist source tracks to library tracks you already own
Source:
Wishlist / Sync
Result:
Found
Management
Backup Manager
Create, download, restore and manage database backups
Last Backup:
Never
Backups:
0
Latest Size:
—
DB Size:
—
Metadata Cache
Cached API responses from Spotify & iTunes
Artists:
0
Albums:
0
Tracks:
0
Hits:
0
Download Blacklist
Blocked sources that won't be used for future downloads
Blocked:
0
Watchlist
Wishlist
0
Album Tracks
0
Singles
Albums/EPs
Next Cycle
