SoulSync - Intelligent Music Discovery & Automation Platform

Spotify-quality music discovery for self-hosted libraries. Automates downloads, curates playlists, monitors artists, and organizes your collection with zero manual effort.

IMPORTANT: Configure file sharing in slskd to avoid Soulseek bans. Set up shared folders at http://localhost:5030/shares.

Community: Discord | Support: GitHub Issues | Donate: Ko-fi

What It Does

SoulSync bridges streaming services to your media server with automated discovery:

Monitors artists → Automatically detects new releases from your watchlist
Generates playlists → Release Radar, Discovery Weekly, Seasonal, Decade/Genre mixes, Cache-powered discovery
Downloads missing tracks → From Soulseek, Deezer, Tidal, Qobuz, HiFi, YouTube, or any combination via Hybrid mode
Verifies downloads → AcoustID fingerprinting for P2P sources (skipped for trusted API sources)
Enriches metadata → 9 enrichment workers (Spotify, MusicBrainz, iTunes, Deezer, AudioDB, Last.fm, Genius, Tidal, Qobuz)
Tags consistently → Picard-style MusicBrainz release preflight ensures all album tracks get the same release ID
Organizes files → Custom templates for clean folder structures
Syncs media server → Plex, Jellyfin, or Navidrome stay updated automatically
Scrobbles plays → Automatic scrobbling to Last.fm and ListenBrainz from your media server

Key Features

Discovery Engine

Release Radar — New tracks from watchlist artists, personalized by listening history

Discovery Weekly — 50 tracks from similar artists with serendipity weighting

Seasonal Playlists — Halloween, Christmas, Valentine's, Summer, Spring, Autumn (hemisphere-aware)

Personalized Playlists (12+ types)

Recently Added, Top Tracks, Forgotten Favorites
Decade Playlists (1960s-2020s), Genre Playlists (15+ categories)
Because You Listen To, Daily Mixes, Hidden Gems, Popular Picks, Discovery Shuffle, Familiar Favorites
Custom Playlist Builder (1-5 seed artists → similar artists → random albums → shuffled tracks)

Cache-Powered Discovery (zero API calls)

Undiscovered Albums — albums by your most-played artists that aren't in your library
New In Your Genres — recently released albums matching your top genres
From Your Labels — popular albums on labels already in your library
Deep Cuts — low-popularity tracks from artists you listen to
Genre Explorer — genre landscape pills with artist counts, tap for Genre Deep Dive modal

ListenBrainz — Import recommendation and community playlists

Beatport — Full electronic music integration with genre browser (39+ genres)

Multi-Source Downloads

6 Download Sources: Soulseek, Deezer, Tidal, Qobuz, HiFi, YouTube — use any single source or Hybrid mode with drag-to-reorder priority

Deezer Downloads — ARL token authentication, FLAC lossless / MP3 320 / MP3 128 with automatic quality fallback and Blowfish decryption

Tidal Downloads — Device-flow OAuth, quality tiers from AAC 96kbps to FLAC 24-bit/96kHz Hi-Res

Qobuz Downloads — Email/password auth, quality up to Hi-Res Max (FLAC 24-bit/192kHz)

HiFi Downloads — Free lossless via public API instances, no account required

Soulseek — FLAC priority with quality profiles, peer quality scoring, source reuse for album consistency

YouTube — Audio extraction with cookie-based bot detection bypass

Hybrid Mode — Enable any combination of sources, drag to set priority order, automatic fallback chain

Playlist Sources: Spotify, Tidal, YouTube, Deezer, Beatport charts, ListenBrainz, Spotify Link (no API needed)

Post-Download

Lossy copy creation: MP3, Opus, AAC with configurable bitrate (Opus capped at 256kbps)
Hi-Res FLAC downsampling to 16-bit/44.1kHz CD quality
Blasphemy Mode — delete original FLAC after conversion
Synchronized lyrics (LRC) via LRClib
Picard-style album consistency — pre-flight MusicBrainz release lookup ensures all tracks get the same release ID

Listening Stats & Scrobbling

Listening Stats Page — Full dashboard with Chart.js visualizations

Overview cards: total plays, listening time, unique artists/albums/tracks
Timeline bar chart, genre breakdown donut with legend
Top artists visual bubbles, top albums and tracks with play buttons and cover art
Library health: format breakdown bar, enrichment coverage rings, database storage chart
Time range filters: 7 days, 30 days, 12 months, all time

Scrobbling — Automatic Last.fm and ListenBrainz scrobbling from Plex, Jellyfin, or Navidrome

Audio Verification

AcoustID Fingerprinting (optional) — Verifies downloaded files match expected tracks

Automatically skipped for trusted API sources (Deezer, Tidal, Qobuz, HiFi)
Only runs for P2P (Soulseek) and extracted audio (YouTube) where mislabeling is possible
Fail-open design: verification errors never block downloads

Metadata & Enrichment

9 Background Enrichment Workers: Spotify, MusicBrainz, iTunes, Deezer, AudioDB, Last.fm, Genius, Tidal, Qobuz

Each worker independently processes artists, albums, and tracks
Pause/resume controls on dashboard, auto-pause during database scans
Error items don't auto-retry in infinite loops (fixed in v2.1)

Dual-Source Metadata

Primary: Spotify — richer data, discovery features, playlist sync
Fallback: iTunes/Apple Music or Deezer — configurable, no authentication required
MusicBrainz enrichment with Picard-style album consistency

Post-Processing Tag Embedding

Granular per-service tag toggles (18+ MusicBrainz tags, Spotify/iTunes/Deezer IDs, AudioDB mood/style, Tidal/Qobuz ISRCs, Last.fm tags, Genius URLs)
Album art embedding, cover.jpg download
Spotify rate limit protection across all API calls

Advanced Matching Engine

Version-aware matching: strictly rejects remixes when you want the original (and vice versa)
Unicode and accent handling (KoЯn, Bjork, A$AP Rocky)
Fuzzy matching with weighted confidence scoring (title, artist, duration)
Album variation detection (Deluxe, Remastered, Taylor's Version, etc.)
Streaming source results bypass filename-matching engine (API results trusted directly)
Short title protection: prevents "Love" from matching "Loveless"

Automation

Automation Engine — Visual drag-and-drop builder for custom workflows

Triggers: Schedule, Daily/Weekly Time, Track Downloaded, Batch Complete, Playlist Changed, Discovery Complete, Signal Received, and 10+ more
Actions: Process Wishlist, Scan Watchlist, Refresh Mirrored, Discover Playlist, Sync Playlist, Scan Library, Database Update, Quality Scan, Full Cleanup, and more
Then Actions: Fire Signal (chain automations), Discord, Telegram, Pushbullet notifications
Pipelines: 11 pre-built one-click pipeline deployments (Release Radar, Discovery Weekly, Nightly Operations, etc.)
Signal Chains: playlist_id forwarded from events to action handlers for proper chain execution

Watchlist — Monitor unlimited artists with per-artist configuration

Release type filters: Albums, EPs, Singles
Content filters: Live, Remixes, Acoustic, Compilations
Auto-discover similar artists, periodic scanning

Wishlist — Failed downloads automatically queued for retry with auto-processing

Mirrored Playlists — Mirror from Spotify, Tidal, YouTube, Deezer and keep synced

Automatic refresh detects changes, discovery pipeline matches metadata
Followed Spotify playlists with 403 errors fall back to public embed scraper

Local Profiles — Multiple configuration profiles with isolated settings, watchlists, and playlists

Library Management

Dashboard — Service status, system stats, activity feed, enrichment worker controls

Unified glass UI design across all tool cards, service cards, and stat cards

Library Page — Artist grid with staggered card animations, per-artist enrichment coverage rings

Artist Radio button — play random track with auto-queue radio mode
Play buttons on Last.fm top tracks sidebar

Enhanced Library Manager — Toggle between Standard and Enhanced views

Inline metadata editing, per-service manual matching
Write Tags to File (MP3/FLAC/OGG/M4A), tag preview with diff
Server sync after tag writes (Plex, Jellyfin, Navidrome)
Bulk operations, sortable columns, multi-disc support

Library Maintenance — 10+ automated repair jobs

Track Number, Dead Files, Duplicates, Metadata Gaps, Album Completeness, Missing Cover Art, AcoustID Scanner, Orphan Files, Fake Lossless, Library Reorganize, Lossy Converter, MBID Mismatch, Album Tag Consistency
Enrichment workers auto-pause during database scans
One-click Fix All with findings dashboard

Database Storage Visualization — Donut chart showing per-table storage breakdown

Import System — Tag-first matching, auto-grouped album cards, staging folder workflow

Template Organization — $albumartist/$album/$track - $title and 10+ variables

Built-in Media Player

Stream tracks from your library with queue system
Now Playing modal with album art ambient glow and Web Audio visualizer
Smart Radio mode — auto-queue similar tracks by genre, mood, and style
Repeat modes, shuffle, keyboard shortcuts, Media Session API

Mobile Responsive

Comprehensive mobile layouts for Stats, Automations, Hydrabase, Issues, Help pages
Artist hero section, enhanced library track table with bottom sheet action popover
Enrichment rings, filter bars, and discover cards all adapt to narrow screens

Installation

Docker (Recommended)

curl -O https://raw.githubusercon

SoulSync

Install / Use

README