61618c2fc7
Apple Music added as fallback metadata source if Spotify is not available. Spotify is always preferred if it is available with its richer data responses. Will easily swap from Spotify to Apple Music on the fly if you are rate limited by Spotify or worse, temp banned. Apple Music and Spotify will now each have their own discovery pool for the discover page. Both will always be updated on every watchlist scan so long as Spotify is authorized, otherwise only Apple Music data is pulled. **Known issues:** Any artist image pulled while Apple Music is the primary source will only pull album art for that artist since they do not provide artist images :( This can, very rarely, lead to cases where the album image that is pulled could have another another artist displayed if it's some collab single, EP or something. Seen it happen once with an indie artist so it's possible. Looking for a great api / website to parse easily specifically for artist names and a huge db to pull from. |
||
|---|---|---|
| assets | ||
| config | ||
| core | ||
| database | ||
| logs | ||
| services | ||
| templates | ||
| tools | ||
| ui | ||
| utils | ||
| webui | ||
| .dockerignore | ||
| .gitattributes | ||
| .gitignore | ||
| beatport_unified_scraper.py | ||
| docker-compose.yml | ||
| DOCKER-OAUTH-FIX.md | ||
| DOCKER-TRANSFER-GUIDE.md | ||
| DOCKER.md | ||
| DOCKER_PERMISSIONS.md | ||
| Dockerfile | ||
| entrypoint.sh | ||
| license.txt | ||
| main.py | ||
| METADATA-FALLBACK-IMPLEMENTATION.md | ||
| README-Docker.md | ||
| README.md | ||
| requirements-webui.txt | ||
| requirements.txt | ||
| UNRAID.md | ||
| web_server.py | ||
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
- 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
Key Features
Discovery Engine
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
Multi-Source Downloads
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
Metadata & Reliability
Dual-Source System
- Primary: Spotify (Preferred for richer data and discovery features)
- Backup: iTunes (No authentication required)
- Redundancy: System automatically manages both sources. If Spotify is authorized, it is prioritized. If Spotify is unavailable, rate-limited, or unauthorized, SoulSync seamlessly switches to iTunes for metadata, cover art, and artist tracking.
- Fail-Safe: Even with Spotify authorized, iTunes metadata is maintained as a redundant layer to ensure zero downtime.
Advanced Matching
- 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
Automation
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
Library Management
- 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)
Installation
Docker (Recommended)
curl -O https://raw.githubusercontent.com/Nezreka/SoulSync/main/docker-compose.yml
docker-compose up -d
# Access at http://localhost:8008
Python
git clone https://github.com/Nezreka/SoulSync
cd SoulSync
pip install -r requirements-webui.txt
python web_server.py
# Open http://localhost:8008
Quick Setup
Prerequisites
- slskd on port 5030 (Download)
- Spotify API credentials (Dashboard)
- Media Server (optional): Plex, Jellyfin, or Navidrome
Configuration
-
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
Who Should Use This
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
Comparison
| 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.
Architecture
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
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
Troubleshooting
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
Roadmap
Planned
- WebSocket support (replace polling)
- Batch wishlist operations
- Download history browser UI
- Source reliability tracking
- Notification center
- Mobile-responsive improvements
Under Consideration
- MusicBrainz ID integration
- Additional streaming sources (Deezer, Apple Music)
- Playlist collaboration between instances
- Machine learning for matching
License
MIT License - See LICENSE file for details
Acknowledgments
Services: slskd, music-map.com, LRClib.net, Spotify, Tidal, Plex, Jellyfin, Navidrome
Community: Contributors, testers, and users providing feedback
