{{ vite_assets('head')|safe }}
🔒

## SoulSync is Locked

Enter your PIN to continue

🔑

## Verify Your Identity

Enter any API key, token, or secret you configured in SoulSync settings

## Who's listening?

Forgot PIN?

### Manage ProfilesCreate, edit & control access for everyone on this instance

#### Add Profile

Home Page
Page Access
Dashboard Sync Search Discover Watchlist Wishlist Automations Downloads Library Listening Stats Playlist Explorer Import Help & Docs Issues
Can download music

#### Admin PIN

Required when multiple profiles exist

###
My Settings

## System Dashboard

Monitor your music system health and manage operations

🎵 MusicBrainz Enrichment
Status: Idle
No active matches
Progress: 0 / 0
🎶 AudioDB Enrichment
Status: Idle
No active matches
Progress: 0 / 0
🎧 Deezer Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Spotify Enrichment
Status: Idle
No active matches
Progress: 0 / 0
iTunes Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Last.fm Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Genius Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Tidal Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Qobuz Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Discogs Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Amazon Music Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Similar Artists Enrichment
Status: Idle
No active matches
Progress: 0 / 0
Hydrabase P2P Mirror
Status: Active
🔧 Library Repair
Status: Idle
No active repairs
Progress: 0 / 0
SoulID Generator
Status: Idle
No items processing
Progress: 0 pending

### Service Status

Connection health for every service SoulSync uses.

Metadata Source ●

Disconnected

Response: --

Media Server ●

Disconnected

Response: --

Download Source ●

Disconnected

Response: --

Enrichment Services

### System Stats

Live performance metrics.

Active Downloads

0

Currently downloading

Finished Downloads

0

Completed this session

Download Speed

0 KB/s

Combined speed

Active Syncs

0

Playlists syncing

System Uptime

0m

Application runtime

Memory Usage

--

Current usage

### Library

Your collection at a glance.

#### Library

Checking status...

0 Artists
0 Albums
0 Tracks
-- DB Size
Scanning...
0 / 0

### Recent Syncs

Playlists you've synced.

### Quick Actions

Three control rooms inside SoulSync.

### Recent Activity

What just happened.

📊

System Started

Dashboard initialized successfully

Now

### Active Downloads

In-flight transfers from your sources.

### Enrichment Services

API rate monitoring across providers.

## Playlist Sync

Synchronize your Spotify, Tidal, and YouTube playlists with your media server

### Your Spotify Playlists

Click 'Refresh' to load your Spotify playlists.

### Your Tidal Playlists

Click 'Refresh' to load your Tidal playlists.

### Your Deezer Playlists

Click 'Refresh' to load your Deezer playlists.

### Your Qobuz Playlists

Click 'Refresh' to load your Qobuz playlists.
Paste a Deezer playlist URL above to get started.
Parsed YouTube playlists will appear here.
Paste a Spotify playlist or album URL above to load tracks without needing Spotify API credentials.
Paste an iTunes or Apple Music album/track URL above to load tracks.

### My Beatport Playlists

Your created Beatport playlists will appear here.

## 🎯 Loading Fresh Beatport Tracks...

Fetching the latest music from Beatport

## 🏆 Top 10 Lists

Current trending tracks from Beatport charts

### 🎵 Beatport Top 10

Most popular tracks on Beatport

#### 🎵 Loading Beatport Top 10...

Fetching trending tracks

### 🔥 Hype Top 10

Editor's hottest trending picks

#### 🔥 Loading Hype Top 10...

Fetching editor's picks

## 💿 Top 10 Releases

Most popular albums and EPs on Beatport

#### 💿 Loading Top 10 Releases...

Fetching trending albums and EPs

## 🆕 New Releases

Latest albums and EPs from Beatport

### 📀 Loading New Releases...

Fetching the latest albums and EPs

## 🔥 Hype Picks

Editor selected trending tracks from Beatport

### 🔥 Loading Hype Picks...

Fetching the hottest trending tracks

## 🔥 Featured Charts

Top chart collections from Beatport creators

### 📊 Loading Featured Charts...

Fetching top chart collections

## 🎧 DJ Charts

Curated charts from top DJs and artists

### 🎧 Loading DJ Charts...

Fetching curated DJ selections

### Import Playlist from File

📄
Drop your file here
or click to browse
Supported: CSV, TSV, TXT
CSV / TSV First row as headers (e.g. Title, Artist, Album). Columns are auto-detected or can be mapped manually.
TXT One track per line (e.g. Artist - Title). Format and separator can be adjusted after upload.
Line format:
Separator:
Column mapping:

# | Track | Artist | Album
--- | --- | --- | ---

### SoulSync Discovery Playlists

Click 'Refresh' to load your personalized SoulSync Discovery playlists.

### Your Last.fm Radio Playlists

Click 'Refresh' to load your Last.fm Radio playlists. Generate new ones from the Discover page.

### Your ListenBrainz Playlists

Click 'Refresh' to load your ListenBrainz playlists.

### Mirrored Playlists

Playlists you parse from any service will appear here as persistent backups.

### Server Playlists

Playlists from your media server will load automatically.

### Multiple Sources Found

####

No mirrored playlist found matching this name. Showing server tracks only.
Source
Server

## Search

Find artists, albums, and tracks from any metadata source

Enter an artist, album, or track name to search
Type
Format
Sort

Enter a search term to get started.

✨
🔗

Searching across Spotify and your library...

🔍

No results found

📚

#### In Your Library

0
🎤

#### Artists

0
💿

#### Albums

0
🎶

#### Singles & EPs

0
🎵

#### Tracks

0

### Search Results

Search results will appear here when you select an album or track.

## Automations

Configure scheduled tasks and automated workflows

⚡
No automations yet
Create your first automation to schedule tasks and trigger actions automatically.

##
Downloads

No downloads yet. Start one from Search, Sync, Discover, or Library.

### Batches

Recent History

## Music Library

Browse your complete music collection

0 Artists
🔍
Loading artists...
🎵
No artists found
Try adjusting your search or filters
Page 1 of 1
🎵

# Artist Name

0 listeners
0 plays
Albums
0/0
EPs
0/0
Singles
0/0

Loading artist discography...

⚠️

### Failed to load artist details

An error occurred while loading the artist's discography.

Show
Include
Status
View

### Albums

0 owned 0 missing

### EPs

0 owned 0 missing

### Singles

0 owned 0 missing

### Similar Artists

Discover artists with a similar sound

Finding similar artists...
⚠️ Unable to load similar artists

### Batch Edit Tracks

0 tracks selected

### Write Tags to File

### Write Tags

### Reorganize Album

FEATURED ARTIST

# Loading...

Discover new music tailored to your taste

📀 View Discography
🎧

## Artist Map

Explore the connections between your artists

### Watchlist

Your watched artists and their similar connections

### Genres

Artists clustered by genre across your library and cache

### Explorer

Pick any artist and explore outward through their connections

## Recommended For You

Artists similar to ones across your library — not yet on your watchlist

## Your Artists

Artists you follow across your music services

## Your Albums

Albums you've saved across your music services

Loading your albums...

## Recent Releases

New music from artists you follow

Loading recent releases...

## Seasonal

Seasonal music

## Seasonal Mix

Curated seasonal playlist

⟳ Syncing to media server...
✓ 0 ⏳ 0 ✗ 0 (0%)

## 🎵 Daily Mixes

Personalized mixes based on your taste

## Fresh Tape

New drops from recent releases

⟳ Syncing to media server...
♪ 0 / ✓ 0 / ✗ 0 (0%)

Loading fresh tape...

## The Archives

Curated from your collection

⟳ Syncing to media server...
♪ 0 / ✓ 0 / ✗ 0 (0%)

Loading the archives...

## 🔥 Popular Picks

Trending tracks from new discoveries

⟳ Syncing to media server...
✓ 0 ⏳ 0 ✗ 0 (0%)

## 🌟 Hidden Gems

Underground discoveries waiting for you

⟳ Syncing to media server...
✓ 0 ⏳ 0 ✗ 0 (0%)

## 🔀 Discovery Shuffle

Random tracks from your discovery pool - different every time

⟳ Syncing to media server...
✓ 0 ⏳ 0 ✗ 0 (0%)

## Build a Playlist ?

Create a custom playlist from your favorite artists

How it works:

1. Search and select 1-5 seed artists you like
2. Hit Generate — the app finds similar artists, pulls their albums, and picks tracks at random
3. You get a fresh 50-track playlist mixing your picks with new discoveries

Tip: The more seed artists you add, the more varied the playlist will be.

### Seed Artists

0 / 5
Search above to add seed artists
Finding similar artists and building your playlist...

### Generated Playlist

⟳ Syncing to media server...
✓ 0 ⏳ 0 ✗ 0 (0%)

## 📻 Last.fm Radio

Search a track to generate a similar-tracks playlist

## 🧠 ListenBrainz Playlists

Playlists from ListenBrainz

Loading playlists...

## ⏰ Time Machine

Explore music from different decades

Loading decades...

## 🎵 Browse by Genre

Discover music by your favorite genres

Loading genres...

## Playlist Explorer

Select a playlist above, then explore
0 albums selected
Scroll to zoom · Right-drag to pan · Double-click album for tracks

Select a playlist to explore

Choose a mirrored playlist and mode above, then click Explore to build the discovery tree

Building tree...

## Settings

Configure services, downloads, and preferences

### API Configuration

#### Metadata Source

Primary 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.
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

›
Client ID:
Client Secret:
Redirect URI:
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
Use Spotify (no auth) for background enrichment
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

›
Storefront Country:
Sets the primary Apple Music storefront. Region-specific albums are auto-searched across other storefronts as fallback.

#### Deezer (Favorites & Playlists)

›
App ID:
App Secret:
Redirect URI:
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):
ARL Token:
Log into deezer.com → DevTools (F12) → Application → Cookies → copy the `arl` value. Provides playlist access + downloads.

#### Discogs

›
Personal Access Token:
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)

›
Client ID:
Client Secret:
Redirect URI:
Current Redirect URI:
http://127.0.0.1:8889/tidal/callback
Add this URL to your Tidal app configuration

#### Qobuz (Metadata & Enrichment)

›
Email:
Password:
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:
Auth Token:
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

›
API Key:
API Secret:
Get your API key and secret from Last.fm API Account
API key: used for metadata enrichment. API secret: required for scrobbling.
Scrobble plays to Last.fm

#### Genius

›
Client Access Token:
Get your token from Genius API Clients
Generate a "Client Access Token" — no OAuth flow needed.

#### AcoustID Verification

›
Enable Download Verification
Verifies downloaded audio matches expected track using fingerprints
API Key:
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

›
API Base URL:
User Token:
Get your token from ListenBrainz Settings
Self-hosted? Enter your server URL (e.g. http://localhost:8093)
Scrobble plays to ListenBrainz

#### Hydrabase

›
WebSocket URL:
API Key:
Auto-connect on startup
P2P metadata network. When enabled and connected, replaces Spotify/iTunes as the primary metadata source for searches.

### Server Connections

Plex Server URL:
Plex Token:
Music Library:
Select which music library to use (doesn't affect config file)
Plex PIN Code
Go to https://plex.tv/link and enter the code shown above.
Jellyfin Server URL:
API Key:
API Timeout (seconds): Timeout for bulk API requests during database sync (15-300s). Increase if your Jellyfin server is slow to respond.
Jellyfin User
Select which user's music library to scan
Music Library
Select which music library to use (doesn't affect config file)
Navidrome users should enable Real Path in the Navidrome player/settings so SoulSync can resolve imported and synced files correctly.
Navidrome Server URL:
Username:
Password:
Music Library
Select which music library to import from

#### Standalone Mode

SoulSync manages your library directly without an external media server. Import your existing music first: move files into the import folder, then use a separate music/output folder for the processed library SoulSync creates.

### Download Settings

These are container-internal paths. Only modify them if you know what you're doing — incorrect values will break downloads.
Input Folder (Download Dir):
Output Folder (Music Library):
Import Folder:
Music Videos Dir:
M3U Entry Base Path:
Optional prefix added to every track path in exported M3U files. Use this when your media server needs absolute paths (e.g. `/mnt/music`).
Download Source:
Choose where to download music from. Hybrid mode tries primary source first, then falls back to secondary if it fails.
Stream / Preview Source:
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.
Concurrent Downloads:
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.
Drag to reorder source priority. Enable sources you want to use. Downloads try each enabled source in order. The first source can use album-level downloads when supported; later sources stay track-level fallback.
slskd URL:
API Key:
Search Timeout (seconds): How long to search for tracks (15-300 seconds)
Search Timeout Buffer (seconds): Extra time to wait for late results (5-60 seconds)
Minimum Delay Between Searches (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.
Minimum Peer Upload Speed:
Ignore search results from peers with upload speed below this threshold
Max Peer Queue Length:
Skip peers with a queue longer than this (prefers peers with shorter queues regardless)
Download Timeout (minutes): Abandon stuck downloads after this many minutes
Auto-clear slskd search history Automatically cleans old searches from slskd when over 200 entries. Disable if you want to keep manual searches in slskd's queue.
Tidal Download Quality:
Audio quality for Tidal downloads. HiRes requires a Tidal HiFi Plus subscription.
Allow quality fallback
When disabled, only downloads at the exact quality selected. If unavailable, skips to the next source.
Tidal Download Auth:
Qobuz Download Quality:
Audio quality for Qobuz downloads. Hi-Res requires a Qobuz Studio or Sublime subscription.
Allow quality fallback
When disabled, only downloads at the exact quality selected. If unavailable, skips to the next source.
Qobuz Account:
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.
HiFi Download Quality:
Audio quality for HiFi downloads. Uses public API instances — no account required.
Allow quality fallback
When disabled, only downloads at the exact quality selected. If unavailable, skips to the next source.
HiFi Status:
Free lossless downloads via community-run hifi-api instances. No authentication or subscription needed.
API Instances:
Deezer Download Quality:
Audio quality for Deezer downloads. FLAC requires a Deezer HiFi subscription. MP3 320 requires Premium or higher.
Allow quality fallback
When disabled, only downloads at the exact quality selected. If unavailable, skips to the next source.
Deezer ARL Token:
Your ARL token authenticates with Deezer. To get it: log into deezer.com → open browser DevTools (F12) → Application tab → Cookies → copy the `arl` value.
Deezer Status:
Amazon Music Quality:
Preferred codec tier. FLAC is 24-bit/48kHz Hi-Res — no subscription required. Downloads via T2Tunes proxy.
Allow quality fallback
Fall back to the next codec tier if the preferred one is unavailable.
Connection:
No account required — T2Tunes is a public Amazon Music proxy.
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.
SoundCloud Status:
Lidarr URL:
Full URL to your Lidarr instance (e.g. http://192.168.1.100:8686)
API Key:
Found in Lidarr → Settings → General → Security → API Key
Lidarr Status:
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.
📡 Torrent and Usenet downloads run through your Prowlarr indexers and your configured downloader. Set up Prowlarr + the torrent / usenet client on the Indexers & Downloaders tab. Once Test Connection is green on both, this source is ready to use.
YouTube Browser Cookies:
If YouTube shows "Sign in to confirm you're not a bot", select your browser here. SoulSync will use your browser's YouTube cookies to authenticate.
YouTube Download Delay:
Seconds between YouTube downloads to avoid bot detection. Default: 3
▼

### Quality Profile

Format priorities, bitrate, bit depth

### 🎵 Quality Profile

Quick Presets:
FLAC (Lossless) Priority: 1
Bitrate Range:
500 kbps - 10000 kbps
Bit Depth:
Accept other bit depths as fallback
When enabled, accepts any FLAC rather than rejecting on bit depth mismatch
MP3 320 kbps Priority: 2
Bitrate Range:
280 kbps - 500 kbps
MP3 256 kbps Priority: 3
Bitrate Range:
200 kbps - 400 kbps
MP3 192 kbps Priority: 4
Bitrate Range:
150 kbps - 300 kbps
Allow fallback to any quality if preferred qualities unavailable
How it works: Downloads try each enabled quality in priority order (1 = highest). MIN bitrate catches fake/transcoded files (e.g., FLAC below 500 kbps is likely a re-encoded MP3). MAX bitrate limits hi-res files if you want to save space. When track duration is unavailable, a generous file-size safety net is used instead.
▼

### Retry Logic

Next-best candidate, exhaustive per-source retry

### 🔁 Retry Logic

Controls what happens when a downloaded file is rejected (AcoustID mismatch, wrong version, or duration/integrity failure). Independent of post-processing.
Retry next-best candidate on mismatch When a download is quarantined (AcoustID mismatch or duration/integrity failure), automatically try the next-best candidate instead of failing the track. Off = quarantine and fail immediately.
Exhaustive retry (separate budget per source) 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.
Retries per query (per source) In exhaustive mode, how many candidates to try per search query per source. The per-source budget is number of search queries × this value. Only used when Exhaustive retry is on.
Accept best version mismatch as last resort 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.
Minimum matching mismatches before accepting How many quarantined candidates must have failed the same version mismatch before the last-resort acceptance kicks in. Higher = more confirmation that no correct version exists. Only used when the option above is on.
Indexers & Downloaders
1 Indexers find releases → 2 Downloader fetches them → 3 SoulSync imports to library
Configure your Prowlarr instance to feed search results, and pick a torrent client and/or usenet client to handle the actual downloads. You only need to set up the protocols you actually use.
💡 Filesystem access — easiest setup
Torrent and usenet clients write files to their own download folders, not Soulseek's. SoulSync needs read access to those folders to import the files. Simplest fix: point all your downloaders (Soulseek, qBittorrent, SABnzbd / NZBGet) at the same download folder. One folder, one path to worry about, everything just works.

- Bare-metal: just set every client's download path to the same folder (e.g. your existing slskd folder). Done.
- Docker: easiest is to reuse the `./downloads` mount you already have for slskd — point qBit and SAB at `/downloads` inside their containers too. Or use the commented placeholders in `docker-compose.yml` if you want separate folders.
- Remote client (NAS / different host): mount the remote folder locally (SMB / NFS / rclone) before SoulSync can see it.

▼

### 🔎 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 `prowlarr.com` (or your *arr stack). You point Prowlarr at your indexers, then point SoulSync at Prowlarr.
Prowlarr URL:
Full URL to your Prowlarr instance (e.g. `http://192.168.1.100:9696`).
API Key:
Found in Prowlarr → Settings → General → Security → API Key.
Restrict to indexer IDs (optional):
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.
Status:
Configured Indexers:
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.
Client Type:
qBittorrent: WebUI port (default 8080). Transmission: RPC port (default 9091). Deluge: WebUI port (default 8112).
WebUI URL:
Username:
qBittorrent and Transmission use username + password. Deluge uses password only — paste it in the password field below.
Password:
Category / Label:
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.
Save Path (optional):
Override where the torrent client writes downloads. This path is on the torrent client's machine, not SoulSync's.
Stalled torrent timeout (minutes):
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).
When a torrent stalls:
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.
Status:
▼

### 📰 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.
Client Type:
SABnzbd: default WebUI port 8080. NZBGet: default WebUI port 6789.
WebUI URL:
API Key:
SABnzbd → Config → General → API Key. Used by SABnzbd only.
Username:
Password:
Category / Label:
SoulSync tags every NZB with this category so it ends up in a predictable post-processing folder.
Status:
▼

### Paths & Organization

File templates, music library paths

### 📁 File Organization

Enable custom file organization templates
Album Path Template: 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
Single Path Template: Variables: $albumartist, $artist, $artistletter, $title, $track (01), $album, $albumtype, $year, $quality (filename only). Use ${var} to append text: ${albumtype}s → Singles
Playlist Path Template: Variables: $playlist, $albumartist, $artist, $artistletter, $title, $year, $quality (filename only). Use ${var} to append text
Music Video Path Template: Variables: $artist, $artistletter, $title, $year. Use ${var} to append text. Default: $artist/$title-video
Multi-Disc Folder Label:
Label used for auto-created disc subfolders on multi-disc albums.
Collaborative Album Artist:
How $albumartist resolves for albums with multiple artists. "First Listed" uses only the primary artist for folder names (e.g., "Larry June" instead of "Larry June, Curren$y & The Alchemist"). Full artist list is always preserved in file metadata tags.
Artist Tag Separator:
Separator between multiple artists in the ARTIST tag
Write multi-value ARTISTS tag Write each artist as a separate tag value for Navidrome/Jellyfin multi-artist support
Move featured artists to title Keep only primary artist in ARTIST tag, append others as (feat. ...) in title
Allow duplicate tracks across albums When enabled, the same song can be added to the wishlist from different albums (e.g., completing a discography where albums share tracks). When disabled, tracks with the same name and artist are skipped.
Restores original path structure. Your downloads will be organized like before.

### 📂 Music Library Paths

Tell SoulSync where your music files live. Required for tag writing, streaming, and file detection when your media server stores files at a different path than SoulSync can see. Docker users: mount your music folder(s) into the SoulSync container with read-write access, then add the container-side path here (e.g. `/music`).
▼

### Post-Processing

Metadata, tags, conversion, lyrics

### 🎵 Post-Processing

Enable post-processing on downloaded files Master toggle — disabling this skips all metadata, artwork, and lyrics processing
Core Features
Embed album art into file
Download cover.jpg to album folder
Use MusicBrainz Cover Art Archive for album art 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.
Preferred album art sources 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.
Generate .lrc lyrics files (LRClib)
Apply ReplayGain tags after download Analyzes loudness and writes ReplayGain track gain/peak tags. Requires ffmpeg. Adds a few seconds per track.
Duration tolerance (seconds) 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.
▶ Spotify 3 tags
Track ID Artist ID Album ID
▶ iTunes 3 tags
Track ID Artist ID Album ID
▶ MusicBrainz 18 tags
Recording ID Artist ID Release ID Release Group ID Album Artist ID Release Track ID Release Type Original Date Release Status Release Country Barcode Media Total Discs Catalog Number Script ASIN ISRC Genres
▶ Deezer 4 tags
Track ID Artist ID BPM ISRC
▶ AudioDB 4 tags
Track ID Mood Style Genre
▶ Tidal 5 tags
Track ID Artist ID ISRC Copyright BPM
▶ Qobuz 5 tags
Track ID Artist ID ISRC Copyright Label
▶ Last.fm 2 tags
Genres URL
▶ Genius 2 tags
Track ID URL
▶ HiFi 5 tags
Track ID Artist ID ISRC BPM Copyright
▶ General 2 tags
Quality Audio quality (e.g. FLAC, MP3-320) Genre Merging Merge genres from Spotify + enabled sources
Supported Formats:
MP3, FLAC, MP4/M4A, OGG

### 📀 Post-Download Conversion

Downsample Hi-Res FLAC to CD quality (16-bit / 44.1kHz)
When a 24-bit or high sample rate FLAC is downloaded, it will be automatically converted to 16-bit/44.1kHz. The hi-res original is replaced — not kept alongside. Requires ffmpeg.
Create lossy copy of downloaded FLAC files
Codec:
Bitrate:
After downloading a FLAC, a lossy copy at the selected codec and bitrate will be created in the same folder. Requires ffmpeg.
Blasphemy Mode — Delete original FLAC after conversion
Warning: The original high-quality file will be permanently deleted. Only the lossy copy will remain.
▼

### Library Preferences

Import, content filter, playlists, stats

### 📊 Listening Stats

Enable listening stats collection from media server
Poll Interval (minutes):
Polls your active media server (Plex, Jellyfin, or Navidrome) for play history and displays stats on the Stats page.

### 🔒 Security

Set Admin PIN:
You need to set a PIN before enabling the lock screen.

Require PIN to access SoulSync
When enabled, a lock screen appears on every page load. PIN is verified against the admin account. Closing the browser tab requires re-entry.
Allowed WebSocket Origins:
Origins (full URL, no trailing slash) allowed to open WebSocket connections to this instance — one per line, or comma-separated. Leave empty for same-origin only (the secure default; works for direct access and most reverse-proxy setups). Add your public domain here if you reach SoulSync via a reverse proxy or custom domain and the WebSocket fails to connect. Use `*` on its own line to allow any origin (insecure — only do this if you understand why you need it).
Behind a reverse proxy
Enable only if SoulSync runs behind nginx / Caddy / Traefik that terminates HTTPS. Trusts the proxy's `X-Forwarded-*` headers, marks the session cookie HTTPS-only, and adds security headers. Leave OFF for direct or LAN access over http:// — turning it on would make the session cookie HTTPS-only and break plain-HTTP access. Takes effect after a restart. See `Support/REVERSE-PROXY.md`.
Auth proxy user header (optional):
If an auth proxy (Authelia / Authentik / oauth2-proxy) logs users in in front of SoulSync, enter the header it sets (e.g. `Remote-User`) and SoulSync will skip the launch PIN for already-authenticated requests. Only set this behind a proxy that strips any client-supplied copy of the header — otherwise it can be spoofed. Leave blank to disable (the default).

### 🔍 Discovery Pool Settings

Lookback Period:
Controls how far back to scan when adding new artists or refreshing discovery pool. Once scanned, artists are kept updated with new releases only.
Hemisphere:
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

Accent Color:
Changes the accent color across the entire UI
Custom Color:
Sidebar Visualizer:
Audio-reactive visualizer on the sidebar edge when music is playing
Background Particles Animated particle effects behind each page. Disable to reduce GPU usage.
Worker Orbs Dashboard header buttons animate as floating orbs. Hover the header to expand. Desktop only.
Reduce Visual Effects Disables backdrop blur, animations, transitions, and shadows. Significantly reduces GPU/CPU usage on low-end devices.

### Database Settings

Concurrent Workers:
Number of parallel threads for database updates. Higher values = faster updates but more server load.

### Database Maintenance

Database Size: Loading...
Free Pages: Loading...
Auto-Vacuum Mode: 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.

### 🔞 Content Filter

Allow explicit content in downloads
When disabled, tracks marked as explicit on Spotify will be skipped during matched downloads. Does not affect manual Soulseek searches.

### 🎵 Genre Whitelist

Enable strict genre filtering
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.

### 📥 Import Settings

Replace lower quality files on import
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.

### 📋 M3U Playlist Export

Auto-save M3U file when downloading playlists
Saves an M3U playlist file alongside your music. Albums are skipped — they're already grouped by your media server.

### Playlist Sync Settings

Sync mode:
"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.
Create playlist backups before sync

### Logging

Log Level:
Controls the level of detail in application logs. DEBUG shows all details, INFO shows general operations, WARNING and ERROR show only issues.
Log Path:
logs/app.log

### SoulSync API

#### REST API Keys

Generate API keys to access SoulSync remotely via the `/api/v1/` endpoints. Keys are shown once at creation — store them securely.
Loading...
New Key Label:
Copy this key now — it won't be shown again!
``

#### 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

Password:
Inactive
Auto-scroll
Initializing log viewer...
0 lines ● Live

## Hydrabase

Disconnected
WebSocket URL
API Key

### API Calls

#### Tracks

{ "request": { "type": "track", "query": "" }, "nonce": 0 }

#### Albums

{ "request": { "type": "album", "query": "" }, "nonce": 0 }

#### Artists

{ "request": { "type": "artists", "query": "" }, "nonce": 0 }

#### Discography

{ "request": { "type": "discography", "query": "" }, "nonce": 0 }

#### Album Tracks

{ "request": { "type": "album.tracks", "query": "" }, "nonce": 0 }

### Response

API responses will appear here

### Network

Peers: --

### Source Comparisons

When Hydrabase is the active metadata source, searches are compared against Spotify and iTunes in the background.

No comparisons yet. Search with Hydrabase active to generate comparisons.

##
Tools & Operations

Database management, library scanning, metadata, backups

### Library Maintenance

Automated scanning, detection, and repair of library issues

Enabled
Loading jobs...
Select All
Loading findings...
Loading history...

### Database & Scanning

#### Database Updater

Last Full Refresh: Never

Artists: 0
Albums: 0
Tracks: 0
Size: 0.0 MB

Idle

0 / 0 artists (0.0%)

#### Quality Scanner

Scan library for tracks below quality preferences

Processed: 0
Quality Met: 0
Low Quality: 0
Matched: 0

Ready to scan

0 / 0 tracks scanned (0.0%)

#### Import IDs from File Tags

Read provider IDs (Spotify, MusicBrainz, iTunes, Deezer…) already embedded in your files and fill them into the database — lets enrichment workers skip redundant API lookups. Only fills blanks; never overwrites an existing match.

IDs Filled: 0
Rows Updated: 0
Conflicts: 0
Unreadable: 0

Ready to scan

0 / 0 files scanned (0.0%)

#### Duplicate Cleaner

Detect and remove duplicate tracks in output folder

Files Scanned: 0
Duplicates Found: 0
Deleted: 0
Space Freed: 0 MB

Ready to scan

0 files scanned (0.0%)

#### Media Server Scan

Manually trigger Plex media library scan for music

Last Scan: Never
Status: Idle

Ready to scan

Waiting for scan request

### Metadata & Cache

#### Metadata Updater

Updates artist photos, genres, and album art from Spotify.

Current Artist: Not running

0 / 0 artists (0.0%)

#### Discovery Pool

View and fix matched/failed discovery results across all mirrored playlists

Matched: —
Failed: —

#### Manual Library Match

Map wishlist and playlist source tracks to library tracks you already own

Source: Wishlist / Sync
Result: Found

### Management

#### Backup Manager

Create, download, restore and manage database backups

Last Backup: Never
Backups: 0
Latest Size: —
DB Size: —

#### Metadata Cache

Cached API responses from Spotify & iTunes

Artists: 0
Albums: 0
Tracks: 0
Hits: 0

#### Download Blacklist

Blocked sources that won't be used for future downloads

Blocked: 0

##
Watchlist

0 artists Next Auto: --
Scanning
0 found
0 added
Waiting…
starting…
—
—
Added to wishlist this run
⚠️ Global override is active — per-artist settings are being ignored during scans.
Last scan: --
Select All

### Your watchlist is empty

Use Search to find an artist, then add them to your watchlist from the artist page.

## ⭐ Wishlist

0 tracks Next Auto: --
0 Album Tracks
0 Singles
Albums/EPs Next Cycle
0 selected
Loading tracks...

### Your wishlist is empty

Failed downloads and tracks from watchlist scans will appear here automatically.

Processing...
Playing from
No track
Unknown Artist
Unknown Album
View Artist
0:00
0:00 0:00
Next
No lyrics loaded
Queue is empty

## Match track download to release

### Step 1: Select the correct Artist

Choose the artist that best matches your download

#### Top Suggestions

#### Or, Search Manually

### Step 2: Select the correct Album

Choose the album that best matches your download for

#### Top Suggestions

#### Or, Search Manually

## SoulSync

I built this app because I wanted it, not to make money. SoulSync is and always will be free. If it's saved you time or you just want to show some love, any support is genuinely appreciated.

Ko-fi

## What's New in SoulSync

Version {{ soulsync_base_version }} — Latest Changes
×

### Tracks to Add to Wishlist

All tracks from this release will be added to your wishlist

×

### Download Preferences

Select which types of releases to monitor for this artist

💿
Albums Full-length studio albums
🎵
EPs Extended plays (4-6 tracks)
🎶
Singles Single tracks and 2-3 track releases

### Content Filters

Check to INCLUDE, leave unchecked to EXCLUDE (default: all excluded)

🎤
Include Live Versions Check to include live performances and concerts
🎧
Include Remixes Check to include remix versions and edits
🎸
Include Acoustic Versions Check to include acoustic and stripped versions
📀
Include Compilations Check to include greatest hits and collections
🎹
Include Instrumentals Check to include instrumental, karaoke, and backing track versions

### Scan Lookback

How far back to look for releases on first scan of this artist

### Scan Source

Override which metadata provider is used when scanning this artist for new releases

### Linked Artist

The metadata provider artist linked to this watchlist entry

## Global Watchlist Settings

Override per-artist settings for all watchlist scans.

🌐
Enable Global Override When enabled, the settings below apply to ALL artists, ignoring individual artist configs

### Release Types

Select which release types to download for all artists

💿
Albums Full-length studio albums
🎵
EPs Extended plays (4-6 tracks)
🎶
Singles Single tracks and 2-3 track releases

### Content Filters

Check to INCLUDE, leave unchecked to EXCLUDE (default: all excluded)

🎤
Include Live Versions Live performances and concerts
🎧
Include Remixes Remix versions and edits
🎸
Include Acoustic Versions Acoustic and stripped versions
📀
Include Compilations Greatest hits and collections
🎹
Include Instrumentals Instrumental, karaoke, and backing track versions
✅
Include Everything Enable all release types AND content filters (live, remixes, acoustic, compilations, instrumentals)

### Custom Exclusion Terms

Comma-separated terms — tracks or albums matching any term will be skipped during scans

Applied globally to all watchlist scans regardless of override setting. Case-insensitive substring matching.

## 🎵 Browse by Genre

🔍

🔍 Discovering current Beatport genres...

### Tool Information

### Library History

### Sync History

### Metadata Cache Browser

Spotify 0
iTunes 0
Deezer 0
Beatport 0
MusicBrainz 0
Discogs 0
Total Hits 0
Searches 0

### Entity Detail

## Confirm

## Spotify Rate Limited

Spotify has temporarily blocked API access. All Spotify features (search, enrichment, playlists) are paused until the ban expires.

Ban Duration —
Triggered By —
Time Remaining —

While rate limiting is active, Spotify-specific features are unavailable. You can wait for the ban to expire or disconnect Spotify to clear it immediately.

{{ vite_assets('body')|safe }}
/
{% include 'track-detail-modal.html' %}
0%
No track
Unknown Artist
0:00 0:00
Play a track to get started