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.
Keep exploring
This Week
Upcoming episodes from your shows
Watchlist
Shows and people you follow
Requests
Titles members asked for — approving one sends it straight into acquisition.
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
Acquisition History
—
Cast & Crew
Details
Videos
Photos
Review
Where to Watch
Collection
More Like This
Acquisition History
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
💾 Backups
Verified snapshots of the video database (wishlist, watchlist, history, settings). The nightly automation keeps a rolling set; restore stages a swap for the next restart — your current database is set aside, never deleted.
✏️ Mass Rename
Re-render every file name to your current naming templates (Settings → Organization). Preview first — nothing moves until you apply. Subtitles and sidecars travel with their file; the server re-adopts the names on its next scan.
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.
Search
Find artists, albums, and tracks from any metadata source
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.
Ratio
or hours seeded
Enforced by
Both at 0 = never remove (the old behavior). SoulSync: SS polls the client and removes when a goal is hit (your imported library copy is separate and never touched). Torrent client: SS writes the ratio/time limit into the client (arr-style) and lets it enforce — it shows in the client's share-limit dialog and works even when SS is off.
Everything on a list enters acquisition automatically (movies → wishlist, shows → follow with the chosen monitor policy).
Only NEW list members are added, so removing something never boomerangs back. Synced by the "Sync Import Lists" automation.
Ref: a TMDB list id, a chart key (trending_movies, top_shows, …), an IMDb ls-id/URL — Plex Watchlist needs no ref.
Get told when things happen — a Discord webhook, any generic webhook (raw JSON), or a Telegram bot.
Each connection picks which events it cares about.
▼
Quality
Ladder, cutoff, rejects & tie-breakers
Profiles apply per title: everything uses Default unless you assign another profile from a movie/show's Manage panel. 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
Minimum seeders At least 1 seeder
A torrent nobody is seeding never finishes — it parks on "downloading metadata" or stalls at 0% and quietly fills your client with dead entries.
Set 0 to grab regardless. Usenet and Soulseek have no seeders and are never affected.
Custom Formats
Score releases by their name — prefer trusted groups, bury x265, chase freeleech, anything a pattern can see.
Terms are plain substrings, or regex written
/x265|hevc/. A format matches when all "match" terms hit and no "never" term does;
matching formats add their score to a release's rank (negative buries without rejecting).
The "this profile" column overrides a format's score for the profile selected above.
Releases whose summed format score falls below this are rejected outright. 0 = off.
▼
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.
Takes effect after a restart, since the worker threads are created at startup.
How long to wait on a streaming source's API during search (HiFi, Qobuz, Deezer, and the stream preview search).
0 (or blank) = each source's built-in default — HiFi/Qobuz 15s, Deezer 10s. Raise it if a slow
connection makes searches give up too early; lower means failing over to the next source faster. Clamped to 5–120.
Soulseek is not affected — it has its own Search Timeout setting above.
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.
Skip releases the indexer reports as having fewer seeders than this, instead of queueing something nobody is serving and waiting for it to time out. Releases that report no seeder count (usenet, and indexers that omit the field) are never skipped. 0 disables.
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.
Ratio
or hours seeded
Enforced by
Both at 0 = never remove (the old behavior). SoulSync: SS polls the client and removes when a goal is hit (your imported library copy is separate and never touched). Torrent client: SS writes the ratio/time limit into the client (arr-style) and lets it enforce — it shows up in the client's share-limit dialog and works even when SS is off.
▼
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
How files flow: Download Folder (raw downloads land here) → post-processing
(tagging, artwork, organizing) → Music Library Folder (their final home — point
your media server here). Keeping the two separate stops half-finished files being scanned.
Docker / Unraid detected: leave these as the container-internal paths and map your
real folders in the container config — wrong values here break downloads.
Bare metal / Proxmox LXC / systemd: there is no container, so you're expected to
unlock these and point them at your real folders.
New downloads are refused when the download disk drops below this. Stops a full disk from hanging the whole system (0 = off).
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).
Hot-swaps a path prefix on every entry when M3Us are generated, so a playlist written inside a container (
/data/media/…) plays directly on the machine that mounts the same storage elsewhere (M:/media/…). Entries that don't start with the prefix pass through unchanged. Leave both empty to disable.
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 when a release has multiple artists — this governs the FOLDER your music sorts into for both albums and singles (the default templates use $albumartist). "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.
When
$artistletter is used in templates: artists starting with digits, symbols or non-Latin scripts all sort into a single # folder instead of one folder per character ("365 Days" → #/, "北京" → #/). Accented letters fold to their base letter (Édith Piaf → E/). Off = the literal first character, exactly as before.
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.
When you remove or cancel a wishlist track, SoulSync remembers not to re-add it automatically for this many days. Lower it (e.g. 7) to give removed tracks another chance sooner.
Restores original path structure. Your downloads will be organized like before.
Additional Music Libraries
Your Music Library Folder above is already covered — you don't need to repeat it here.
Add entries only for extra libraries SoulSync should read (a second collection, an archive
drive), or when your media server sees the same files at a different path than SoulSync can.
Used for tag writing, streaming, and file detection.
Docker users: mount the extra folder(s) into the SoulSync container with read-write access,
then add the container-side path here (e.g.
/music2).
Library Organize
When the Library Organize tool re-matches a track, the metadata source often
differs from files you've already organized: capitalization, release year (a
reissue [2023] "corrected" to the source's 2020), or disc layout (a single-disc
album matched to a deluxe 2-disc edition, stamping a bogus "0211" prefix). With
this on (default), a title/album differing only by letter-case, your own
album year, and a genuinely single-disc album's numbering are all left alone —
no needless renames. Turn off to match the metadata source exactly.
▼
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.
▼
yt-dlp
Version & one-click update ●
Loading...
Loading...
YouTube changes how it serves video far more often than yt-dlp cuts a stable release, so nightly is what actually keeps downloads working. Stable is there if you'd rather move slowly.
When YouTube downloads start failing with 403 Forbidden, an out-of-date yt-dlp is nearly always the cause.
An update only takes effect after you restart SoulSync — the running process keeps using the version it loaded at startup.
▼
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.
Spotify often only carries one cut of a track. With a version picked here,
a matching file wins over the plain one when both turn up in the same
Soulseek search. Nothing is ever skipped — if that version isn't out
there, the normal one downloads exactly as it does now. Off by default.
Live, remix, acoustic and instrumental files are normally thrown out on sight when the source didn't ask for one. Picking any of those four here lifts that for the version you picked, so a live take of a similarly titled song can be accepted when the real track is nowhere to be found.
Live, remix, acoustic and instrumental files are normally thrown out on sight when the source didn't ask for one. Picking any of those four here lifts that for the version you picked, so a live take of a similarly titled song can be accepted when the real track is nowhere to be found.
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
▼
Artwork Cache
Local copies of cover & poster art
Loading...
Loading...
Oldest-unused art is removed once the cache passes this size. 0 means no limit.
Off by default. When on, SoulSync resizes art server-side so a grid of tiles
doesn't pull full-size originals — the big win on large libraries, at the cost
of some CPU the first time each image is seen. Everything else about the cache
is unchanged.
Nothing here is irreplaceable — every image is re-downloaded on demand, so
clearing only costs a slower first load.
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.
Chat
Soulseek rooms & private messages
