Library
Movies and shows from your media server
0
Movies
Search
Movies, TV shows & people — everything stays in-app
Live torrent board
Sourced from EXT.to
🎞
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
An endless mix of movies & shows
Watchlist
Shows and people you follow
Requests
What your household asked for. Approve once, everyone who asked hears about it.
Import
Downloads that need a hand — place them by hand or dismiss
Automations
Video tasks that keep your movie & TV library fresh — separate from the music side
—
Needs attention
Subtitle languages
Fetching the full episode list from TMDB… missing episodes will fill in
shortly.
Playlists
Cast & Crew
Collection
More Like This
Videos
Photos
About
Where to Watch
Review
Acquisition History
—
Needs attention
Subtitle languages
Cast & Crew
Collection
More Like This
Videos
Photos
About
Where to Watch
Review
Acquisition History
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
Connections
Accounts, media servers, and
API keys SoulSync connects to
Metadata Source
Where artist,
album, and track metadata comes from:
• Spotify — official Spotify; connect your account with the Spotify tile under Services.
• 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; the public server is limited to 1 request/sec. Configure a self-hosted server in the MusicBrainz tile under Services.
• 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 with the Spotify tile under Services.
• 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; the public server is limited to 1 request/sec. Configure a self-hosted server in the MusicBrainz tile under Services.
• 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.
Services
Accounts and API keys SoulSync connects
to
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.
API Configuration
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. Spotify requires
HTTPS for any URI that isn't loopback — on a NAS or
remote server, enter an HTTPS proxy URL in the
Redirect URI field above instead
(see Help & Docs → Getting Started).
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.Concerts
›
Adds a Live section to artist pages. Both are
optional and
independent — set up either, both, or neither.
Upcoming dates, venues and ticket links. Free self-service key
from
developer.ticketmaster.com (5,000 calls a day).
Two letters, like US or GB. Keeps the concerts in your Discover
inbox to one country. Leave it empty for everywhere. Artist
pages always show every date.
What the artist actually played at recent shows, song by song
— and a
setlist can be played straight from your library. Free key from
setlist.fm/settings/api (non-commercial use).
Last.fm
›
The Last.fm account whose listening history to import. You
can correct this username here or on the Stats page.
Get your API key and secret from Last.fm API
Account
API key: used for metadata enrichment.
API secret: required for scrobbling.
Genius
›Pollinations
›Makes cover art for playlists, from the ⋯ menu on any playlist.
Works without a key: one image every 45 seconds, with a small Pollinations mark in the corner.
A key from enter.pollinations.ai removes the mark and the wait.
MusicBrainz
›
Optional:
enter your self-hosted server address. Leave blank to use public
MusicBrainz. Applies to search, matching and enrichment as soon
as settings are saved.
For a fixed
limit, enter requests/second (for example, 10). With No limit
(adaptive), SoulSync will try to find the maximum number of
requests/second your server can handle. Only use this when you
host the MusicBrainz server yourself and it has no other traffic.
Public MusicBrainz always keeps its rate limit. Environment
overrides take precedence over these fields. Your server needs
search indexes; use its final URL.
AcoustID Verification
›
Verifies downloaded audio matches expected track using
fingerprints
Requires an Application API key (not your user account key) — register a free application at acoustid.org/new-application
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)
Maloja: use http://your-server:42010/apis/listenbrainz
and your Maloja API key. Start history sync from Stats.
Hydrabase
›P2P metadata network. When enabled and
connected, replaces Spotify/iTunes as the primary metadata
source for searches.
API Configuration
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)
Subtitle downloads, plus which
subtitle languages exist per title.
SubDL (Subtitles)
›Get a free key from SubDL
(account panel)
SubSource (Subtitles)
›Get a free key from SubSource
(profile page)
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. A library ticked Anime files
its shows' new episodes in the Anime folder (Settings > Library).
Server Connections
▼
Video 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
Audio language for
dubbed or MULTI releases. a release with no language tag is
the original audio
Save to which library
new titles on this profile are filed in. the 4K library is
used once its folder is switched on in Settings > Folders,
until then they go to the main one. titles you already have
stay put
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.
Available
drag one across, or click it
Download chain
Download Sources
Set up any source here, then put it in the chain on the Downloads tab. A source does not have to be enabled to be configured.
💡 Filesystem access — easiest setup ▾
How long to search
for tracks (15-300 seconds)
Extra time to wait
for late results (5-60 seconds)
Forces a gap between
consecutive searches. Smooths burst patterns
that trip ISP anti-abuse (e.g. Bell Canada
cuts the WAN after rapid peer-connection
spikes). 0 disables.
Ignore search results from peers with
upload speed below this threshold
Skip peers with a queue longer than
this (prefers peers with shorter queues regardless)
Off by default. Applies to automatic
tracks and album bundles when another eligible peer is
available; not manually chosen files.
When enabled, try the next Soulseek
candidate after roughly one minute below this observed speed.
Uses actual byte progress rather than the peer's advertised
speed. The final available candidate is always allowed to
continue. 0 also disables.
Abandon stuck downloads after this many
minutes
Automatically cleans old searches from
slskd when over 200 entries.
Disable if you want to keep manual searches in slskd's
queue.
Which transfers and searches cleanup
removes. Leave on "own" if other apps (Lidarr, another
SoulSync, slskd's own UI) share this slskd. "Everything" clears
all clients' finished downloads and is only safe when SoulSync
is the only user.
Requires a paid Qobuz subscription. Streams are DRM-free.
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 for X-User-Auth-Token in the request
headers → copy that value.
Free lossless downloads via community-run hifi-api instances. No
authentication or subscription needed.
Heads up: some HiFi instances only have
30-second Tidal previews for certain tracks, with headers faked
to look like the full song. SoulSync decodes every HiFi download
to catch these and never lets a shorter clip replace a good
library file, but if a track just won't come through at full
length here, grab it from another source.
Your ARL token authenticates with Deezer. To get it:
log into deezer.com
→ open browser DevTools (F12) → Application tab → Cookies → copy
the
arl value.
SoundCloud downloads run anonymously — no account required. Use
this for DJ mixes,
remixes, and tracks that aren't on Spotify/Tidal/Deezer.
Quality: 128 kbps MP3 / AAC depending on the upload (anonymous tier). SoundCloud doesn't expose lossless audio to anyone.
Quality: 128 kbps MP3 / AAC depending on the upload (anonymous tier). SoundCloud doesn't expose lossless audio to anyone.
Full URL to your Lidarr instance (e.g.
http://192.168.1.100:8686)
Found in Lidarr → Settings → General → Security → API Key
Uses Lidarr's indexers and download clients (Usenet/torrent) for
album downloads.
Best for full-album grabs. Lidarr is album-first by design — track-name searches usually return nothing useful, so in hybrid mode Lidarr is mostly a no-op for playlists and falls through to your other sources. Use Lidarr Only when you specifically want to grab whole albums via your indexers.
Best for full-album grabs. Lidarr is album-first by design — track-name searches usually return nothing useful, so in hybrid mode Lidarr is mostly a no-op for playlists and falls through to your other sources. Use Lidarr Only when you specifically want to grab whole albums via your indexers.
Only needed for private playlists, your Liked Music, age-gated
videos
and Premium audio qualities — public videos download fine
with None.
Reading a browser only works when that browser is on the same
machine as SoulSync,
so on a server or in Docker choose Paste
cookies.txt. On Windows,
Chrome and the other Chromium browsers seal their cookies in a
way yt-dlp cannot
read at all — use Firefox or
Paste cookies.txt.
Seconds between YouTube downloads to avoid bot detection.
Default: 3
For an album, find the album itself on YouTube Music and
download its playlist, instead of searching for each song.
Helps with albums whose songs never show up in a song
search. The artist and album title must both match; if
they don't, SoulSync searches track by track as usual.
Some albums need YouTube Music Premium cookies.
Off by default.
YouTube serves Opus or AAC, not FLAC or MP3.
With this on, the quality list must include the converted format
(default MP3 320). With it off, add Opus or AAC to the list,
or turn Fallback on.
yt-dlp ●
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.
⬢ 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 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.
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.
Per-indexer overrides
Sonarr/Radarr put seed rules on the indexer, not
globally — a private tracker needs a ratio or a
week of seeding, a public one needs nothing.
Leave a box blank to inherit the goal
above; type 0 to exempt that tracker
from it. Pack hrs is the longer window
season packs get (blank = same as Hours).
Click Load indexers to list
the torrent indexers from Prowlarr.
⬢ 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.
▼
Music 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.
Acquisition vs retained output: Downsample and Lossy Copy run only after the downloaded file passes this gate. SoulSync remembers the acquired quality, so intentionally retaining 16/44.1 or a lossy-only output does not make the same track appear as an upgrade again.
Acquisition vs retained output: Downsample and Lossy Copy run only after the downloaded file passes this gate. SoulSync remembers the acquired quality, so intentionally retaining 16/44.1 or a lossy-only output does not make the same track appear as an upgrade again.
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."
▼
Album Releases
Profile What to import when a Usenet or torrent download is a whole album
A requested track often arrives inside a whole album release.
Requested tracks only imports just the track you asked for.
Also the album's other tracks then imports every other track of that album found in the release and not yet in your library. Each one goes through the normal import pipeline with this quality profile, like a wishlist download: a track that fails a check is quarantined on its own, and the tracks that pass are imported.
Also the album's other tracks then imports every other track of that album found in the release and not yet in your library. Each one goes through the normal import pipeline with this quality profile, like a wishlist download: a track that fails a check is quarantined on its own, and the tracks that pass are imported.
▼
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. Its acquired quality is remembered for upgrade decisions, preventing a
download/downsample loop. Requires ffmpeg.
After downloading a
lossless file, a lossy derivative at the selected codec and
bitrate is created in the same folder. When the source is
kept, it remains the canonical quality and the derivative is
treated as a companion version. Requires ffmpeg.
One profile, two decisions: the quality list
controls what SoulSync acquires;
these options control what it retains. A retained lossless +
lossy pair is one track with two
file versions, not two duplicate tracks.
▼
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.
Opt-in second integrity
tier: a FLAC that passes the size/parse/duration checks is
fully decoded with
flac -t, which also verifies
the STREAMINFO MD5. A file that fails is quarantined and
the next candidate is tried, so a damaged replacement can
never take the place of a good file. Off by
default. Fails open — if the flac binary is
missing or the check times out, the file is left alone
rather than quarantined.Quality Profiles
Click a profile's name to view/edit its settings on the left. Changes autosave to that profile, and Save Settings saves it too; viewing never activates it. Per row: ● set as active default, ✏ rename, ✎ save now, ⇩ use for Auto-Import, × delete.
▼
Download Behaviour
Preview source, concurrency & timeouts
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.
"Deezer 30s Preview" plays Deezer's 30 second clip of the
song straight away, no Deezer account needed. Songs Deezer
has no clip for use YouTube. With queue auto-download off,
missing queue songs play their clip instead of being
skipped.
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.
▼
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. That private staging area is SoulSync's
own working folder,
storage/album_bundle_staging/<batch id> — it is
not the Staging path set under Library, which is a
different folder for a different job. It is emptied when the batch
finishes. If a crash leaves one behind, the next start moves
anything still holding audio into the Downloads recycle bin
(labelled “Stalled album download”) rather than deleting
it, so a stalled album is recoverable instead of gone. Only affects
full-album and wishlist-album downloads — single tracks and album
top-ups (completeness fills) are unaffected. Tracks stay on your
wishlist until the album is actually published, so an interrupted
album is always retryable.On by default, and
only relevant when album publishing above is on. If SoulSync
restarts or crashes part-way through an album, the tracks it had
already finished are left in the private staging folder, where no
media server can see them. On the next start SoulSync moves those
finished tracks into your library, and the tracks it never got to
are still on your wishlist, so the album fills itself in. Turn this
off to keep strict quarantine instead: the
interrupted album stays hidden until you deal with it by hand. Files
are never deleted either way.
Files & folders
Where things live on disk, and how they get
named
▼
Folders
Downloads and library locationsMusic foldersDownloads,
library & extra folders
Folder 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).
Entries become
../Artist/Album/01 - Song.flac
instead of the full path SoulSync sees, so a saved M3U still
works when the folder is opened from a network share, another
machine or a sync tool. Tracks that don't share a folder with
the playlist keep their full path, and the base path and
prefix rewrite below still apply to those.
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.
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).
Sample Studio Folders
Where Sample Studio saves your chops — organized
into Artist/Track folders inside the destination. The
first folder is the default; the save dialog lets
you pick a different one per chop (drums here, melodies there, a
folder per project). Keep these outside your
music library so your media server doesn't index chops as albums.
Docker users: mount the folder(s) into the
SoulSync container, then add the container-side path here.
Audiobook foldersWhere finished books live
An existing collection on another
drive. SoulSync scans and manages it, but new books always land
in the folder above. In Docker, mount it at its own container
path, like /app/audiobooks2. If a drive is unplugged, its
books stay in your library until it's back.
Children's audio plays and similar
releases are found by the music search, not the audiobook
search. Downloads by the artists listed here are filed in the
audiobooks folder above instead of the music library, and
count as owned so playlist syncs do not fetch them again.
Add an artist with Treat as audiobook on the
artist's page or in the watchlist settings. Routing only
affects new downloads; Move existing… relocates
albums already in the music library.
Podcast foldersWhere episodes live
Video foldersMovies, TV
& YouTube libraries
Where downloads arrive
Files land in the download folder first, then get renamed and
moved into the right library below. Each folder gets a live check
under it: whether SoulSync can write there and how much room is
left. Video folders are separate from your Music folders.
Docker / Unraid detected: these start on the
container paths your compose file maps. Leave them and map your
real folders in the container config. Unlock one only if you mapped
it somewhere else.
Bare metal / Proxmox LXC / systemd: there is no
container, so unlock each folder and point it at your real one.
Point this at the same folder as
your slskd / torrent / usenet client. It's the same setting as
the Music side's Download Folder, so it's locked here too:
change it and Music changes with it.
Libraries
Where finished downloads are filed. Point your Plex / Jellyfin /
Emby libraries at the same folders.
New episodes of anime shows go
here instead of the TV folder: shows in a TV library ticked Anime
(Settings > Connections), shows set to Anime by hand, and shows
not in your library yet that TMDB suggests are anime (an admin can
change that on the show's page or when approving). Leave empty to
keep anime with TV.
4K libraries (optional)
Keep 4K copies in their own folders, like a separate Movies 4K
library in Plex. Off until you turn one on. A title files here when
its quality profile is set to save to the 4K library (Settings >
Quality). Titles you already have stay where they are, and their
upgrades land beside the copy you have.
Anime keeps its own folder when one
is set, whatever the profile.
Collections on other drives
Extra folders SoulSync scans and manages but never downloads into,
for an existing collection on another drive. Add them to your
Plex / Jellyfin scan too. No need to repeat the main folder.
Docker volumes
In Docker every folder above is a path inside the container. Each
one needs a line in your compose file mapping a real folder to it,
read-write so renames, upgrades and the recycle bin work. These are
the lines for what's set here: swap the left side for the folder on
your machine, then recreate the container.
▼
Organization
Naming, layout and file handlingMusic organizationFile
naming templates & reorganize
File Organization
When a
release carries a MusicBrainz disambiguation (edition note)
and your template doesn't place
$disambiguation itself, it is added to the
album folder automatically. When a recording carries its own
disambiguation (version note, like “acoustic”)
and your template doesn't place
$track_disambiguation itself, it is added to the
track filename automatically. This keeps same-named releases
and same-titled recordings apart — turn it off and your template is
respected exactly as written.
Variables:
$albumartist, $artist,
$artistletter, $albumartistletter,
$album,
$albumtype, $title,
$track, $disc (01),
$discnum (1), $cdnum (CD01),
$year, $quality (filename only),
$disambiguation (the release's edition note, like
“baby punk version”; added to the album folder
automatically when your template leaves it out, unless
“Automatically add disambiguation”
above is turned off),
$track_disambiguation (the recording's version
note, like “acoustic”; added to the filename
automatically when your template leaves it out, unless the
same toggle above is turned off),
$explicit ([E] on explicit tracks, nothing
otherwise), $contentrating ([E] or [C]) and
$contentratingfull ([Explicit] or [Clean]); these
stay empty when the source doesn't say, and in a folder they
follow the album, not the track.
To tell same-named artists apart:
$albumartistdisambiguation (MusicBrainz's note,
like “US grunge band”),
$albumartistcountry (US, GB, JM),
$albumartistgenre,
$albumartistinfo (the first of those three the
artist has), $albumartistcomposite (the note, else
country and genre together, like “US Rock”) and
$albumartistclash (the same as info, but
only when another artist in your library shares the name, so
$albumartist ($albumartistclash) keeps unique
artists plain). The $artist versions
($artistinfo and so on) describe the track
artist. They come from enrichment, so an artist that hasn't
been matched to MusicBrainz yet renders nothing. The
three disc variables work in a folder segment as well as in the
filename and are empty on a single-disc album, so
$albumartist/$album/Disc $discnum/$track - $title
gives you a disc folder only where there is more than one disc.
Put any of them in the template and it replaces the automatic
disc folder from “Multi-Disc Folder Label” below.
Use ${var} to append text:
${albumtype}s → Albums
A soundtrack
or compilation is filed as a compilation
instead of whichever contributor happened to be downloading
— without this, one guitarist featured on 45 soundtracks
collects all 45 albums. Compilations are filed with the
Compilation Path Template below, not the album one. Each track
still credits the artist who actually recorded it. A release
counts as a compilation when it
is credited to Various Artists, when the metadata source types
it one, or — when reorganizing, where the whole tracklist
is known — when three or more tracks have different
artists and none of them owns more than half the album. A
soundtrack credited to a single composer is left with that
composer. Also governs whether reorganize gives compilations
their own folder layout.
Used instead
of the album template for soundtracks and compilations (see
“Detect multi-artist compilations” above).
Same variables as the album template;
$albumartist
is the release's credit (often Various Artists) and
$artist is whoever recorded the track. To file
compilations exactly like albums, give it the same template
as the album one.
Variables:
$albumartist, $artist,
$artistletter, $albumartistletter,
$title,
$track (01), $album,
$albumtype, $year,
$quality (filename only). Use ${var}
to append text: ${albumtype}s → Singles
Variables: $playlist, $albumartist,
$artist, $artistletter, $title, $year, $quality (filename only).
Use ${var} to append text
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
Variables:
$artist, $track,
$album, $chop (the save name),
$stem (drums/vocals/bass/other, empty for the
full mix). Default:
$artist/$track - $chop. Sample Studio files saved
chops inside the chosen sample folder with this layout; every
rendered file also carries its own tags. Empty segments
collapse — a chop with no album info won't leave a stray
folder. Use ${var} to append text.
Label for the
disc subfolder SoulSync adds automatically on a multi-disc album
(
Disc 1/). Ignored when your path template already
places the disc itself with $disc,
$discnum or $cdnum — the
template wins.
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.
Windows
doesn't allow
: ? / \ " * | < > in file or
folder names. Off, they become _
(AC_DC). On, they become lookalike characters
that work everywhere (AC∕DC,
What's Going On？), and a trailing dot is kept
(DAMN․). Applies to new downloads; run
Reorganize to rename what's already there.
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.
Wing It
means a track couldn't be matched in the metadata catalogue
— these are unmatched guesses, not tracks missing from your
library. Off by default: guesses stay in the Wing It Pool for
manual review. Turn this on to let guesses be searched like
any other wishlist track.
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.
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.
When an import creates an artist folder, also write a Kodi-format
artist.nfo containing the artist's name and MusicBrainz
artist ID, so Jellyfin / Kodi / Emby identify the artist instead
of guessing by name. An existing artist.nfo with a
different ID is never overwritten. To backfill folders you
already have, run the Artist NFO Backfill repair job.
Audiobook organizationNaming, quality, tags & recycle
Variables:
$author, $authorletter,
$narrator, $title,
$series, $seriespos (01),
$year, $asin. Default:
$author/$series/$seriespos - $title. Books with no
series collapse the series folder and its number cleanly, the
same way podcast season folders do. Use ${var} to
append text.
Deleting a
book MOVES it to a hidden
.deleted folder inside
your audiobook library instead of erasing it, so a mis-click can
be undone. The folder is hidden so Audiobookshelf, Plex and
Jellyfin do not keep showing books you removed. Note the space
is not freed until the bin is emptied. Off, deletes are
permanent immediately.
days
How long a
deleted book stays recoverable before the daily cleanup erases
it for good. 0 turns the bin off — it
does not mean "erase everything now", because purging on that
reading would destroy what was recycled while the bin was still
on. Default:
7
Audiobook Quality
What counts as a good file. One profile for every audiobook — the per-author card carries the settings that differ by author.
Ranked first
when several releases are otherwise equal; the rest keep their
usual order behind it. M4B is the only format
built for audiobooks — chapters, bookmarks, and one file
instead of ninety. Pick MP3 if your player
cannot read M4B. Format never outweighs having the right book
and the right narrator.
kbps
Hides releases
below this bitrate. 0 means no opinion. This is
taste, and separate from the completeness floor above: that one
asks whether a release could be the whole book at all, this one
asks whether you want it. Audible's own files are 32 kbps mono
and 64 kbps stereo, so 32 is a reasonable floor and anything
above 128 is more than speech needs.
kbps
Hides releases
above this bitrate, for when disk space matters more than
headroom. 0 means no opinion. Speech gains
nothing audible above about 128 kbps, so a 45-hour book at 240
kbps is roughly 4GB for no benefit.
GraphicAudio
and similar full-cast productions with music and sound effects.
They are a different product from the audiobook —
different cast, different running time, usually sold in several
separately-downloaded parts. Left on they are shown but ranked
below real readings and clearly labelled; turned off they are
hidden entirely.
Downloads & Import
Books use the same torrent, usenet and Soulseek clients as music — set those up under Sources.
Which Audible
storefront the audiobook catalogue pages, author scans and
follow checks query. Some titles are exclusive to one country's
store, so picking the store you buy from finds books the US
store never lists. Default:
us
Which sources
a book search asks. Separate from the music chain on purpose
— Tidal, Qobuz, HiFi and Deezer carry no
audiobooks at all, so a book on the music chain would burn an
attempt on each of them before it could succeed. The clients
themselves are the same ones music uses; only the order and the
category differ.
The category
SoulSync tags audiobook torrents and NZBs with in your download
client. Keep it different from your music category so a finished
book is never picked up by anything watching for music. Default:
audiobooks
Newznab
category IDs searched for audiobooks.
3030 is the
standard audiobook category and is deliberately kept OUT of
music searches, so asking for it here costs the music side
nothing. Only change this if your indexer uses a non-standard
ID.
%
How much of
the runtime Audible publishes has to actually be on disk before
a book is filed into your library. A download client reports
"complete" when the files it was asked for finished,
which is not the same as the book being whole — and a book
missing its last chapters plays perfectly until you run out of
it. Short books are held in staging, never failed outright.
Default:
92
days
How long an
incomplete book is kept staged before it is failed and sent back
to the wishlist. Torrents finish late and uploaders repair
releases, so patience is right here; forever would mean one
broken release holds a wishlist row for good. Default:
7
Chapter files
arrive named however the uploader left them. On by default: a
book whose files sort wrong plays wrong. Turn this off only if
you trust your releases' own numbering.
Off by
default: when a book arrives as many files, combine them into
a single
.m4b with one chapter marker per file
during import. Needs ffmpeg on the server
(the Docker image ships it). The originals are only removed
after the merged file verifies, so a failed merge never
loses the book.
Off by default:
a book that is downloaded or found in your library stays on the
wishlist, marked "In library". Turn this on to drop it instead,
the way the music wishlist does.
Embeds title,
author, series and narrator into each file on import. Narrator
goes in the COMPOSER field, which is the convention every
audiobook server settled on. Without this a book keeps whatever
the uploader's ripper wrote, which is usually chapter 4 of a
27-hour book tagged as a track on an album called
"audiobook".
Embeds the
cover into every chapter file. A cover the release already
shipped is preferred over fetching one, so this still works
offline.
Writes
cover.jpg into the book folder. Plex, Jellyfin,
Audiobookshelf and Booksonic all read it from there.
Writes
metadata.opf (Audiobookshelf, Plex, Calibre) and
book.nfo (Kodi, Jellyfin, Emby). Both, because the
servers genuinely disagree about which to look for and they are
a few hundred bytes each. These also carry the ASIN, which is
what lets the daily library scan recognise a book you imported
months ago.
Podcast organizationNaming & media format
Variables:
$show, $author, $title,
$season (01), $seasonnum (1),
$episode (01), $episodenum (1),
$year, $date (YYYY-MM-DD),
$type. Default:
$show/Season $season/$title. Season and episode
folders collapse cleanly if omitted in feed. Use
${var} to append text.
Choose which
formats to store in your podcast folders. Audio
Only keeps standard audio files with embedded tags.
Video Only remuxes the audio into an MP4 video
container with a static high-res episode artwork frame and
Apple/iTunes TV metadata tags so Plex, Jellyfin, and Emby can
catalog them as TV Shows with seasons, episode posters, and
playback resume. Audio & Video keeps both
formats side-by-side in the same folder with shared NFO sidecars
so both Music and TV media libraries can index the same folder
simultaneously.
Video organizationPath templates, post-processing &
recycle
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, $tmdbid, $imdbid, $tvdbid (the show's
ids).
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.
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.
Subtitles
Fetch external .srt files next to
the video from the provider chain below, only for what's
missing. On by default for new imports — free tiers
are quota-limited (~20 downloads/day each), so anything
missed is retried later.
Language codes to fetch, in
priority order (e.g.
en,es). One .srt per
language is written as
<video>.<lang>.srt.
Each code is 2–3 letters;
separate codes with commas, spaces, or semicolons.
A tiebreak only, never a filter:
when two subtitles score the same, the hearing-impaired
one (sound cues, speaker names) wins.
On top of the full track, fetch a
forced (foreign-parts-only) track per language, written as
<video>.<lang>.forced.srt — the lines
for scenes in another language, for when you watch
without full subtitles. Many titles have none, so these
often stay missing.
Before fetching, SoulSync checks what
the video already has: any sidecar next to it
(
.en.srt, .eng.srt,
.English.sdh.srt, or an unlabeled
.srt whose language it detects) and the
file's own embedded tracks.
Ignore image subs if your players
can't show them (or have to transcode for them) and you'd
rather have a text .srt.
After a download, shift the
subtitle timing to match the video's own audio
(ffsubsync, offline). Requires the
ffsubsync Python package on the server;
a failed sync keeps the original file.
Available
drag one across, or click it
Provider chain
faster-whisper Python package on the
server.
Candidates scoring below this are a miss and never download.
Max subtitle downloads per provider per day (UTC).
A new candidate must beat the current subtitle by this much to replace it.
How often the wanted loop retries misses.
Max wanted rows attempted per worker cycle.
Processing
What happens to a file after it arrives
▼
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: files can run 3s short (5s for
tracks >10min) or 15s long. Raise this if tracks
routinely quarantine for being a few seconds off (live
recordings, alternate masterings, CD pregaps). A set value
applies both ways, so anything under 15 also tightens the
long side. Capped at 60s.
Tag Embedding
Toggle a service to
enable/disable all its tags, or expand to control individual
tags.
▶
3 tags
▶
3 tags
▶
19 tags
Beets-style: write the MusicBrainz release-group's
first-release-date as the DATE tag instead of the downloaded
edition's date (a 2016 reissue of a 2010 album gets 2010).
The original date is still kept in ORIGINALDATE either way,
and a more precise same-year date is never replaced by a
vaguer one.
▶
4 tags
▶
4 tags
▶
5 tags
▶
5 tags
▶
2 tags
▶
2 tags
▶
5 tags
▶
6 tags
▶
2 tags
MP3, FLAC, MP4/M4A, OGG
▼
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.
On by default for new installs. Turn this off if
your Music Library
folder is just a scratch
drop area rather than your real, permanent library (served by
Navidrome/Plex/etc.). 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.
0 disables the limit. At 10 MB/min, a 3:30 track
may be up to 35 MB (1 MB = 1,000,000 bytes).
Oversized candidates are skipped before download. Uses the
advertised duration, or the requested track length when unavailable.
Album releases use the album length. Sources without size or
duration information cannot be checked.
This does not resize existing files or limit post-processing output.
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.
Discovery & playlists
Playlists, history and how recommendations
behave
▼
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
Music Library 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.
When on, syncing a playlist adds tracks missing from your
library to the wishlist (which queues them for download).
Turn it off and syncs skip the wishlist step — missing tracks
are never added to the wishlist. (A playlist's own
organize/folder-download setting is separate and still
applies.) The Sync / Sync + download buttons always choose
per click, regardless of this setting.
Replace deletes the playlist on your media server and rebuilds it.
This copies the old server playlist first, so anything you added to
it on the server isn't lost. SoulSync already keeps its own copy of
the source playlist, so turn this off if you don't edit playlists on
the server. Reconcile and Append edit in place, so they normally skip it.
▼
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
Video
Where to watch and what detail pages show
▼
Video Preferences
Trailers & where-to-watch regionDetail Pages
›Plays a muted trailer behind the hero
after a moment (uses more bandwidth).
▼
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.
Adds a "Sign in with Plex" button to the sign-in screen. Anyone
with access to your Plex server signs in with their Plex account
(SoulSync never sees their password), and their playlists sync to
their own Plex account. The server's owner signs in as the admin.
New Plex profiles start with what New sign-ups below sets;
widen them per person under Profiles.
Needs Plex as a media server and internet access to plex.tv.
Adds a sign-in button for your own identity provider (Pocket ID,
Authentik, Authelia, Keycloak or any other OpenID Connect
provider). SoulSync never sees passwords. Create a client at the
provider with this callback URL:
/api/auth/oidc/callback.
New OIDC profiles start with what New sign-ups below sets.
Accounts are matched by the provider's account id, never by email,
and nobody becomes an admin from a provider claim: to sign in as
the admin, save these settings, then connect your own account
at the bottom.
SoulSync sees this connection as plain http, so that's the
callback it sends your provider. Turn on Behind a reverse proxy
below and restart, have your proxy send X-Forwarded-Proto, or
set the Callback URL override to your https address.
Your provider's logo, shown on the sign-in card in My Account
(https only). Leave empty for a plain key icon.
Only accounts in this group get in. Leave empty to let every
account at the provider sign in.
Add the scope your provider needs to send groups, if you set a
required group (Pocket ID:
groups). Add
offline_access on Authentik or Authelia so signing
someone out there signs them out here too.
Only if your reverse proxy doesn't pass the public address through.
Password sign-in, the recovery question, Sign in with Plex
and switching profiles with a password stop working, and
anyone signed in some other way is signed out. Invites send
people to your provider instead of asking for a password.
Needs login mode, and you have to be signed in with OIDC
yourself to turn it on. Every profile needs an OIDC
connection first. Passwords are kept and work again if you
turn this off. If the provider is ever down, set
SOULSYNC_OIDC_ONLY_OVERRIDE=off on the
container and restart, then sign in with the admin password.
What a profile made by sign-in can open. Music: Discover, Search,
Library, Wishlist and Stats. Movies & TV: Discover, Search and
Library on the video side. Request-only profiles also get Requests.
Help and Issues are always there; widen anyone further under
Profiles.
requests every
days
0 means no limit. A request is one movie, show, album or track.
Applies to profiles made after you save; change existing ones
under Profiles.
🌐 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.
▼
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...
A read-only key can fetch library and status data. It cannot
change anything or read settings, keys or profiles.
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.
MCP for AI Clients
Lets Claude and other AI apps search, check your library and
download through SoulSync. Add
http://<host>:8008/mcp as an MCP server and
send an API key from above as a Bearer token. A read-only key
can look but not change anything. Settings, keys and profiles
are never reachable.
Lidarr Compatible API
Lets request apps that only talk to Lidarr (Singarr, MusicSeerr
1.x) use SoulSync instead. In the app, set the Lidarr URL to
http://<host>:8008/lidarr and paste an
Admin API key from above. Albums it asks for
go on the wishlist of the profile below.
Pick a profile without download rights and every request
waits for approval on the Requests page first.
▼
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.
▼
Sidebar Weather
Time, temp & forecast line
No API keys, no setup beyond this — the server looks up the
location and fetches the forecast (Open-Meteo, cached 30 min).
Clear to turn the feature off.
Master switch for the weather line, forecast popover and particle
scene. The scene also respects your OS "reduce motion" setting.
Halloween, Thanksgiving, Christmas, New Year's and Lunar New Year
in the sidebar around each, by your location's date. Christmas Day
always snows.
Auto-detected from the location (°F for US, °C elsewhere) —
flip it here if you prefer the other.
Loading...
▼
MetaSync
Join SIN, the signal network, through the MetaSync companion
MetaSync is a small companion program that runs next to
SoulSync and joins pools for you — the first pool is
SIN, the signal network from step 2 below. Two separate
steps happen on this page, and they are not the same
thing:
Step 1 connects SoulSync and MetaSync to each other, on this machine.
Step 2 joins a pool. MetaSync does the joining — SoulSync itself never talks to a pool, it only hands MetaSync your pool key.
Installing MetaSync joins nothing by itself.
Step 1 connects SoulSync and MetaSync to each other, on this machine.
Step 2 joins a pool. MetaSync does the joining — SoulSync itself never talks to a pool, it only hands MetaSync your pool key.
Installing MetaSync joins nothing by itself.
Connecting pairs the two programs. When you click
Connect, a code appears here and in MetaSync's
dashboard; approve it there and the two programs swap
keys automatically — MetaSync gets a key to read this
SoulSync, SoulSync gets a key to talk to MetaSync.
You never type or see either key.
Not
connected
Where the MetaSync program answers. If it runs on
this same machine, SoulSync finds it on its own
(port 8790) — type an address only if MetaSync
lives somewhere else.
Rather type a key? Connect manually instead of pairing
Pairing above does this for you. The manual way:
in MetaSync's dashboard, create a local API key
and paste it here, then Save. SoulSync ends up
holding the same kind of key either way.
A pool is a network your MetaSync can join. The
first pool is SIN, the SoulSync Intelligence
Network: it collects anonymous taste signals from
SoulSync installs — bulk counts of what people
watchlist and wishlist, never your personal data —
and turns them into shared playlists, like Trending
and Most Wanted, which MetaSync brings back into
this SoulSync. Get a key from your pool account,
put it below, and send it to MetaSync. MetaSync
joins and does all the talking — it swaps your key
for short-lived access tokens, so the key itself
stays between you and MetaSync. Nothing is joined
until you send the key.
No key yet? Get one at the SIN
front desk — sign in there, create a key, then
come back and put it below.
Your own key for the pool, from your pool account.
SoulSync stores it here only so it can hand it to
MetaSync when you click Send — SoulSync never uses
it itself.
Send pool key is the button that joins the pool.
Save only stores what you typed above, for later.
Loading...
Undoes step 1 and
step 2: MetaSync leaves the pool, the key it reads
this SoulSync with is revoked, and SoulSync forgets
MetaSync's key. Your pool key stays saved above.
▼
Developer
Preview tools, nothing saved
Shows any sky or holiday in the sidebar so you can check how it
looks. Only this browser tab sees it and nothing is saved; the
weather line reads "Preview" while it's on. The date pretends
it's another day, which sets the season and the holiday.
Live weather
Runs the real first-run setup over the app. Nothing is saved:
settings, the profile, follows and sign-ins stay in the preview
and are thrown away when you close it. Connection checks still
talk to the real services, read only. A Preview tag stays in the
corner the whole time.
Experimental — proceed with
caution
▼
Notifications
Discord, webhooks & Telegram
Video downloads from slskd, torrent or usenet only. Hybrid tries each
enabled source in order.
Use the arrows
to order sources. Enable the ones you want — downloads try each
enabled source in order.
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.
▼
Import Lists
Auto-add movies & shows from a list
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.
▼
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
👤
Peer Files
Soulseek Peer
Upload Speed
—
Queue Length
—
Free Slots
—
Shared Folders
—
0 files
selected
Post Wanted / ISO Card
Search metadata & post an In Search
Of card to chat
Type 2+ letters to search across
metadata providers
