SoulSync is a self-hosted music download, sync, and library management platform. It connects to Spotify, Apple Music/iTunes, Tidal, YouTube, and Beatport for metadata, and uses Soulseek (via slskd) as the primary download source. Your library is served through Plex, Jellyfin, or Navidrome.
Search and download tracks in FLAC, MP3, and more from Soulseek, with automatic metadata tagging and file organization.
Mirror playlists from Spotify, YouTube, Tidal, and Beatport. Discover official metadata and sync to your media server.
Browse, edit, and enrich your music library with metadata from 7 services. Write tags directly to audio files.
Schedule tasks, chain workflows with signals, and get notified via Discord, Pushbullet, or Telegram.
Discover new artists via similar-artist recommendations, seasonal playlists, genre exploration, and time-machine browsing.
Follow artists and automatically scan for new releases. New tracks are added to your wishlist for download.
After launching SoulSync, head to the Settings page to configure your services. At minimum you need:
SoulSync integrates with many external services. Here's a quick reference for each:
| Service | Purpose | Auth Required |
|---|---|---|
| Spotify | Primary metadata source (artists, albums, tracks, cover art, genres) | OAuth — Client ID + Secret |
| iTunes / Apple Music | Fallback metadata source, always free, no auth needed | None |
| Soulseek (slskd) | Music download source | URL + API key |
| Plex | Media server — library scanning and metadata sync | URL + Token |
| Jellyfin | Media server — library scanning | URL + API Key |
| Navidrome | Media server — auto-detects changes | URL + Username + Password |
| Tidal | Playlist import, optional download source | OAuth — Client ID + Secret |
| Last.fm | Enrichment — listener stats, tags, bios, similar artists | API Key |
| Genius | Enrichment — lyrics, descriptions, alternate names | Access Token |
| AcoustID | Audio fingerprint verification of downloads | API Key |
| ListenBrainz | Listening history and recommendations | URL + Token |
SoulSync uses a sidebar navigation layout. The left sidebar contains links to every page, a media player at the bottom, and service status indicators. The main content area changes based on the selected page.
The dashboard is your command center. At the top you'll see service status indicators for Spotify, your media server, and Soulseek — showing connected/disconnected state at a glance. Below that, stat cards display your library totals: artists, albums, tracks, and total library size.
Stats update in real-time via WebSocket — no page refresh needed.
The header bar contains enrichment worker icons for each metadata service. Hover over any icon to see its current status, what item it's processing, and progress counts (e.g., "142/500 matched").
Workers run automatically in the background, enriching your library with metadata from:
Artist genres, follower counts, images, album release dates, track preview URLs
MBIDs for artists, albums, and tracks — enables accurate cross-referencing
Deezer IDs, genres, album metadata
Artist descriptions, artist art, album info
iTunes/Apple Music IDs, preview links
Listener/play counts, bios, tags, similar artists for every artist/album/track
Lyrics, descriptions, alternate names, song artwork
The dashboard features several tool cards for library maintenance:
| Tool | What It Does |
|---|---|
| Database Updater | Refreshes your library by scanning your media server. Choose incremental (new only) or full refresh. |
| Metadata Updater | Updates artist photos, genres, styles, and biographies from MusicBrainz, Spotify, iTunes, and Last.fm. |
| Quality Scanner | Scans library for tracks below your quality preferences. Shows how many meet standards and finds replacements. |
| Duplicate Cleaner | Identifies and removes duplicate tracks from your library, freeing up disk space. |
| Discovery Pool | View and fix matched/failed discovery results across all mirrored playlists. |
| Retag Tool | Batch retag downloaded files with correct album metadata from Spotify/iTunes. |
| Backup Manager | Create, download, restore, and delete database backups. Rolling cleanup keeps the 5 most recent. |
The activity feed at the bottom of the dashboard shows recent system events: downloads completed, syncs started, settings changed, automation runs, and errors. Events appear in real-time via WebSocket.
The Sync page lets you import playlists from Spotify, YouTube, Tidal, and Beatport. Once imported, playlists are mirrored — they persist in your SoulSync instance and can be refreshed, discovered, and synced to your wishlist for downloading.
If Spotify is connected, click Refresh to load all your Spotify playlists. Each playlist shows its cover art, track count, and sync status.
For each playlist you can:
Paste a YouTube playlist URL into the input field and click Parse Playlist. SoulSync extracts the track list and attempts to match each track to official Spotify/iTunes metadata.
Requires Tidal authentication in Settings. Once connected, refresh to load your Tidal playlists. You can also select Tidal download quality: HQ (320kbps), HiFi (FLAC 16-bit), or HiFi Plus (up to 24-bit).
The Beatport tab has three views: Browse (featured content, genre browsing), Charts (Top 100, Hype charts), and My Playlists. Browse 12+ electronic music genres and download directly from chart listings.
Every parsed playlist from any source is automatically mirrored. The Mirrored tab shows all saved playlists with source-branded cards, live discovery status, and download progress.
For non-Spotify playlists (YouTube, Tidal), tracks need to be discovered before syncing. Discovery matches raw titles to official Spotify/iTunes metadata using fuzzy matching with a 0.7 confidence threshold.
The default search mode. Type an artist, album, or track name and results appear in a categorized dropdown: In Your Library, Artists, Albums, Singles & EPs, and Tracks. Results come from Spotify (or iTunes if Spotify is unavailable).
Toggle to Basic Search mode for direct Soulseek queries. This shows raw search results with detailed info: format, bitrate, quality score, file size, uploader name, upload speed, and availability.
Filters let you narrow results by type (Albums/Singles), format (FLAC/MP3/OGG/AAC/WMA), and sort by relevance, quality, size, bitrate, duration, or uploader speed.
When you select an album or track to download, a modal appears with:
After downloading, files go through post-processing: optional AcoustID fingerprint verification, automatic metadata tagging (title, artist, album, track number, genre, cover art), and organized file placement in your library.
Configure your quality preferences in Settings → Quality Profile. Quick presets:
| Preset | Priority |
|---|---|
| Audiophile | FLAC first, then MP3 320 |
| Balanced | MP3 320 first, then FLAC, then MP3 256 |
| Space Saver | MP3 256 first, then MP3 192 |
Each format has configurable bitrate ranges and a priority order. Enable Fallback to accept any quality when preferred formats aren't available.
Toggle the download manager panel (right sidebar) to see all active and completed downloads. Each download shows real-time progress: track name, format, speed, ETA, and a cancel button. Use Clear Completed to clean up finished items.
The hero slider showcases recommended artists based on your watchlist. Each slide shows the artist's image, name, popularity score, genres, and similarity context. Use the arrows or dots to navigate, or click:
SoulSync generates curated playlists from your discovery pool (50 similar artists refreshed during watchlist scans):
Each playlist can be downloaded or synced to your media server.
Search for 1–5 artists, select them, and click Generate to create a custom playlist from their catalogs. You can then download or sync the generated playlist.
The Discover page includes auto-generated seasonal content based on the current time of year, plus two curated sections:
Both can be synced to your media server with live progress tracking.
Browse discovery pool content by decade — tabs from the 1950s through the 2020s. Each decade pulls top tracks from pool artists active in that era.
Search for any artist by name. Results show artist cards with images and genres. Click a card to see their full discography with albums, singles, and EPs. From the detail view you can download any release or add the artist to your watchlist.
The detail view also shows Similar Artists as clickable bubbles for further exploration.
The watchlist tracks artists you want to follow for new releases. When SoulSync scans your watchlist, it checks each artist's discography and adds any new tracks to your wishlist for downloading.
Click Scan for New Releases or let the system automation handle it (runs every 24 hours). The scan shows a live activity panel with:
Per-Artist Settings — Click the config icon on any watched artist to customize what release types to include: Albums, EPs, Singles, Live versions, Remixes, Acoustic versions, Compilations.
Global Settings — Override all per-artist settings at once. Enable Global Override, select which types to include, and all watchlist scans will follow the global config.
Automations let you schedule tasks and react to events with a visual WHEN → DO → THEN builder. Create custom workflows like "When a download completes, update the database, then notify me on Discord."
Each automation card shows its trigger/action flow, last run time, next scheduled run (with countdown), and a Run Now button for instant execution.
Click + New Automation to open the builder. Drag or click blocks from the sidebar into the three slots:
Add Conditions to filter when the automation runs. Match modes: All (AND) or Any (OR). Operators: contains, equals, starts_with, not_contains.
| Trigger | Description |
|---|---|
| Schedule | Run on a timer interval (minutes/hours/days) |
| Daily Time | Run every day at a specific time |
| Weekly Time | Run on specific weekdays at a set time |
| App Started | Fires when SoulSync starts up |
| Track Downloaded | When a track finishes downloading |
| Download Failed | When a track permanently fails to download |
| Download Quarantined | When AcoustID verification rejects a download |
| Batch Complete | When an album/playlist batch download finishes |
| Wishlist Item Added | When a track is added to the wishlist |
| Wishlist Processing Done | When auto-wishlist processing finishes |
| New Release Found | When a watchlist scan finds new music |
| Watchlist Scan Done | When the full watchlist scan completes |
| Artist Watched/Unwatched | When an artist is added to or removed from the watchlist |
| Playlist Synced | When a playlist sync completes |
| Playlist Changed | When a mirrored playlist detects changes from the source |
| Discovery Complete | When playlist track discovery finishes |
| Library Scan Done | When a media library scan finishes |
| Database Updated | When a library database refresh finishes |
| Quality/Duplicate Scan Done | When quality or duplicate scanning finishes |
| Import Complete | When an album/track import finishes |
| Signal Received | Custom signal fired by another automation |
| Action | Description |
|---|---|
| Process Wishlist | Retry failed downloads (all, albums only, or singles only) |
| Scan Watchlist | Check watched artists for new releases |
| Cleanup Wishlist | Remove duplicate/owned tracks from wishlist |
| Scan Library | Trigger a media server library scan |
| Update Database | Refresh library database (incremental or full) |
| Deep Scan Library | Full library comparison without losing enrichment data |
| Refresh Mirrored Playlist | Re-fetch playlist tracks from the source |
| Sync Playlist | Sync a specific playlist to your media server |
| Discover Playlist | Find official metadata for playlist tracks |
| Run Duplicate Cleaner | Scan for and remove duplicate files |
| Run Quality Scan | Scan for low-quality audio files |
| Clear Quarantine | Delete all quarantined files |
| Update Discovery | Refresh the discovery artist pool |
| Backup Database | Create a timestamped database backup |
| Full Cleanup | Clear quarantine, queue, staging, and search history |
| Notify Only | No action — just trigger notifications |
After the DO action completes, up to 3 THEN actions run:
All notification messages support variable substitution: {name}, {status}, {time}, {run_count}, and context-specific variables from the action result.
SoulSync ships with 10 built-in automations that handle routine maintenance. You can enable/disable them and modify their configs, but you can't delete them or rename them.
| Automation | Schedule |
|---|---|
| Auto-Process Wishlist | Every 30 minutes |
| Auto-Scan Watchlist | Every 24 hours |
| Auto-Scan After Downloads | On batch_complete event |
| Auto-Update Database | On library_scan_completed event |
| Refresh Beatport Cache | Every 24 hours |
| Clean Search History | Every 1 hour |
| Clean Completed Downloads | Every 5 minutes |
| Auto-Deep Scan Library | Every 7 days |
| Auto-Backup Database | Every 3 days |
| Full Cleanup | Every 12 hours |
The Library page shows all artists in your collection as cards with images, album/track counts, and service badges (Spotify, MusicBrainz, Deezer, AudioDB, iTunes, Last.fm, Genius) indicating which services have matched this artist.
Use the search bar, alphabet navigation (A–Z, #), and watchlist filter (All/Watched/Unwatched) to browse. Click any artist card to view their discography.
The artist detail page shows albums, EPs, and singles as cards with completion percentages. Filter by category, content type (live/compilations/featured), or status (owned/missing). At the top, View on buttons link to the artist on each matched external service.
Toggle Enhanced on any artist's detail page to access the professional library management tool:
In the Enhanced view, each artist, album, and track shows match status chips for all 7 services. Click any chip to manually search and link the correct external ID. Run per-service enrichment from the dropdown to pull in metadata from a specific source.
Matched services show as clickable badges linking to the entity on that service's website.
Sync your database metadata to actual audio file tags:
Supports MP3, FLAC, OGG, and M4A via Mutagen. After writing, optional server sync pushes metadata to Plex (per-track update), Jellyfin (library scan), or Navidrome (auto-detects).
Select tracks across multiple albums using the checkboxes. The bulk bar appears showing the selection count with actions:
From any album card showing missing tracks, click Download Missing to open a modal listing all tracks not in your library. Select tracks, choose a download source, and start the download. Progress is tracked per-track with status indicators.
Set your staging folder path in Settings → Download Settings. Place audio files you want to import into this folder. SoulSync scans the folder and detects albums from the file structure.
The import page header shows the total files in staging and their combined size.
The Singles tab handles individual tracks that aren't part of an album.
The sidebar media player is always visible when a track is loaded. It shows album art, track info, a seekable progress bar, and playback controls (play/pause, previous, next, volume, repeat, shuffle).
Click the sidebar player to open the Now Playing modal — a full-screen experience with large album art, ambient glow (dominant color from cover art), a frequency-driven audio visualizer, and expanded controls.
Add tracks to the queue from the Enhanced Library Manager or download results. Manage the queue in the Now Playing modal: reorder, remove individual tracks, or clear all.
Smart Radio mode (toggle in queue header) automatically adds similar tracks when the queue runs out, based on genre, mood, style, and artist similarity. Playback continues seamlessly.
Repeat modes: Off → Repeat All (loop queue) → Repeat One. Shuffle randomizes the next track from the remaining queue.
| Key | Action |
|---|---|
| Space | Play / Pause |
| → | Next track |
| ← | Previous track |
| ↑ | Volume up |
| ↓ | Volume down |
| M | Mute / Unmute |
Media Session API — SoulSync integrates with your OS media controls (lock screen, system tray) for play/pause, next/previous, and seek.
Configure credentials for each external service. All fields are saved to your local config — nothing is sent to external servers except during actual API calls.
Set your preferred audio quality with presets (Audiophile/Balanced/Space Saver) or custom configuration per format. Each format has a configurable bitrate range and priority order. Enable Fallback to accept any quality when nothing matches.
SoulSync supports Netflix-style multiple profiles for shared households. Each profile gets its own:
Shared across all profiles: Music library (files and metadata), service credentials, settings, and automations.
Generate API keys in Settings → API Keys. Use them via header or query parameter:
Authorization: Bearer sk_xxxxx?api_key=sk_xxxxxKeys use a sk_ prefix. The raw key is shown once at creation; only a SHA-256 hash is stored.
| Endpoint | Description |
|---|---|
GET /api/system/status | Uptime and service connectivity |
GET /api/system/stats | Library counts and sizes |
GET /api/library/artists | Paginated artist list with filters |
GET /api/artist-detail/{id} | Full artist info and discography |
POST /api/download | Start a download |
GET /api/downloads/status | Active download status |
POST /api/search | Search Soulseek |
POST /api/enhanced-search | Enhanced metadata search |
GET /api/automations | List all automations |
POST /api/database/backup | Create a backup |
The full API has 90+ endpoints. Use reverse proxy support for external access.