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
SoulSync bridges streaming services to your media server with automated discovery:
- Monitors artists → Automatically detects new releases
- Generates playlists → Release Radar, Discovery Weekly, Seasonal, Decade/Genre mixes
- Downloads missing tracks → From Soulseek, Beatport charts, playlists
- Enriches metadata → LRC lyrics, album art, proper tags
- Organizes files → Custom templates for clean folder structures
- Syncs media server → Plex, Jellyfin, or Navidrome stay updated
Release Radar - 30 new tracks from watchlist artists (updates daily)
Discovery Weekly - 50 tracks from similar artists using custom algorithm
- 20 popular + 20 mid-tier + 10 deep cuts
- Built from 1000+ track discovery pool
- Refreshes every 24 hours
Seasonal Playlists - Halloween, Christmas, Valentine's, Summer, Spring, Autumn (auto-generated)
Personalized Playlists (12+ types)
- Recently Added, Top Tracks, Forgotten Favorites
- Decade Playlists (1960s-2020s), Genre Playlists (15 categories)
- Daily Mixes, Hidden Gems, Popular Picks, Custom Builder
ListenBrainz - Import recommendation and community playlists
Beatport - Electronic music charts by genre (House, Techno, Trance, etc.)
- Top 100, Hype Charts, DJ Charts, Staff Picks
Sources: Soulseek (FLAC priority), YouTube (Audio), Beatport charts, Spotify/Tidal playlists
Features
- Quality profiles: Audiophile, Balanced, Mobile
- Automatic format fallback (FLAC → MP3)
- Duplicate prevention against library
- Batch processing with retry logic
- Synchronized lyrics (LRC) for every track
- Unicode/accent handling (KoЯn, Björk, A$AP Rocky)
- Fuzzy matching with confidence scoring
- Album variation detection (Deluxe, Remastered, etc.)
- Multi-strategy: exact → normalized → fallback
Watchlist - Monitor unlimited artists, auto-discover similar artists via music-map.com
Wishlist - Failed downloads retry every 30 minutes automatically
Background Tasks - Database sync, discovery pool updates, seasonal content
- Quality Scanner - Find low-bitrate files to replace
- Duplicate Cleaner - Identify redundant tracks
- Completion Tracking - Album progress percentages
- Enhanced Search - Unified search across Spotify, library, Soulseek
- Template Organization -
$albumartist/$album/$track - $title(fully customizable)
curl -O https://raw.githubusercontent.com/Nezreka/SoulSync/main/docker-compose.yml
docker-compose up -d
# Access at http://localhost:8008git clone https://github.com/Nezreka/SoulSync
cd SoulSync
pip install -r requirements-webui.txt
python web_server.py
# Open http://localhost:8008- slskd on port 5030 (Download)
- Spotify API credentials (Dashboard)
- Media Server (optional): Plex, Jellyfin, or Navidrome
-
Spotify API
- Create app → Add redirect:
http://127.0.0.1:8888/callback - Copy Client ID and Secret
- Create app → Add redirect:
-
SoulSync Settings
- Enter API credentials
- Configure slskd URL and API key
- Set download/transfer paths
- Connect media server (optional)
- Configure slskd file sharing to avoid bans
-
Docker OAuth Fix (if accessing from remote device)
- Redirected to
http://127.0.0.1:8888/callback?code=... - Manually edit URL to server IP:
http://192.168.1.5:8888/callback?code=... - Spotify requires 127.0.0.1 (banned localhost Nov 2025)
- See DOCKER-OAUTH-FIX.md
- Redirected to
Perfect for:
- Self-hosters with Plex/Jellyfin/Navidrome
- Music enthusiasts with 500+ album collections
- Electronic music fans (Beatport integration)
- Former Spotify users wanting local discovery
Not ideal for:
- Casual users wanting simple sync
- Slow/metered internet connections
- Users uncomfortable with APIs or Docker
| Feature | SoulSync | Lidarr | Headphones | Beets |
|---|---|---|---|---|
| Custom Discovery Algorithm | ✓ | ✗ | ✗ | ✗ |
| Personalized Playlists (12+) | ✓ | ✗ | ✗ | ✗ |
| Beatport Integration | ✓ | ✗ | ✗ | ✗ |
| ListenBrainz Playlists | ✓ | ✗ | ✗ | ✗ |
| Multi-Source (Spotify/Tidal/YouTube) | ✓ | ✓ | ✗ | ✗ |
| Watchlist Monitoring | ✓ (100+) | ✓ | ✓ | ✗ |
| LRC Lyrics | ✓ | ✗ | ✗ | Plugin |
| Advanced Matching | ✓ | ✗ | ✗ | ✓ |
| Quality Scanner + Duplicate Cleaner | ✓ | ✗ | ✗ | ✓ |
| Template-Based Organization | ✓ | ✗ | ✗ | ✓ |
| Seasonal Playlists | ✓ | ✗ | ✗ | ✗ |
SoulSync is the only tool combining intelligent discovery with multi-source automation and library management.
Scale: 83,000+ lines Python, 120+ API endpoints, handles 10,000+ album libraries
Integrations: Spotify, Tidal, YouTube, Plex, Jellyfin, Navidrome, Slskd, ListenBrainz, LRClib, music-map.com, Beatport
Stack: Python 3.8+, Flask, SQLite, PyQt6 (desktop GUI in maintenance mode)
Core Components:
- Matching engine with Unicode/fuzzy logic
- Discovery system with custom algorithms
- Download pipeline with quality profiles
- Metadata enhancement (lyrics, art, tags)
- Template-based file organization
Default Structure
Transfer/Artist/Artist - Album/01 - Track.flac
Custom Templates
- Albums:
$albumartist/$albumartist - $album/$track - $title - Singles:
$artist/$artist - $title/$title - Playlists:
$playlist/$artist - $title - Variables:
$artist,$albumartist,$album,$title,$track,$playlist
Features: Client-side validation, automatic fallback, instant apply
Enable Debug Logging: Settings → Log Level → DEBUG → Check logs/app.log
Common Issues
- Files not organizing: Verify transfer path, check template syntax, use "Reset to Defaults"
- Docker paths: Ensure drives mounted in docker-compose.yml, use
/host/mnt/X/prefix - OAuth from remote: Manually edit callback URL to server IP (Spotify requires 127.0.0.1)
- Wishlist stuck: Auto-retry runs every 30 mins, check logs for failures
- Multi-library: Select correct library in settings dropdown
- WebSocket support (replace polling)
- Batch wishlist operations
- Download history browser UI
- Source reliability tracking
- Notification center
- Mobile-responsive improvements
- MusicBrainz ID integration
- Additional streaming sources (Deezer, Apple Music)
- Playlist collaboration between instances
- Machine learning for matching
MIT License - See LICENSE file for details
Services: slskd, music-map.com, LRClib.net, Spotify, Tidal, Plex, Jellyfin, Navidrome
Community: Contributors, testers, and users providing feedback
