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:

1. Monitors artists → Automatically detects new releases
2. Generates playlists → Release Radar, Discovery Weekly, Seasonal, Decade/Genre mixes
3. Downloads missing tracks → From Soulseek, Beatport charts, playlists
4. Enriches metadata → LRC lyrics, album art, proper tags
5. Organizes files → Custom templates for clean folder structures
6. 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

---

Setup Guide

Prerequisites

• slskd running and accessible (Download)
• Spotify API credentials (Dashboard)
• Media Server (optional): Plex, Jellyfin, or Navidrome

Step 1: Set Up slskd

SoulSync talks to slskd through its API, so you need an API key.

Getting your slskd API key:

1. Open your slskd web UI (usually http://localhost:5030)
2. Go to the settings/options page
3. Find the API keys section - if there isn't one already set, you'll need to add one in your slskd config file (settings.yml)
4. In your slskd config, under web > authentication > api_keys, add a key. It can be literally anything, just make it long enough. Example:

   web:
     authentication:
       api_keys:
         my_key:
           key: "12345678910111213"
   

5. Restart slskd after adding the key
6. Copy that same key - you'll paste it into SoulSync's settings

Making sure SoulSync can see slskd's downloads:

This is the part that trips people up. slskd downloads files to a folder on your system, and SoulSync needs to be able to see that same folder. If both are running in Docker, you need to make sure they're pointed at the same place on disk.

For example, if slskd downloads to /mnt/user/Music/Downloads on your host machine, SoulSync needs a volume mapping that points to that same host folder. In your SoulSync docker-compose or container config, map it like:

volumes:
  - /mnt/user/Music/Downloads:/app/downloads

Then in SoulSync's settings, set the download path to /app/downloads (the container path, not the host path).

Same idea for the transfer/library folder - wherever you want your organized music to end up, map that host folder into the container and use the container path in SoulSync's settings.

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

Step 2: Set Up Spotify API

Spotify is optional but gives you the best discovery features (playlists, recommendations, metadata). Without it, SoulSync falls back to iTunes for search and metadata which works fine for basic downloading.

If you want Spotify features:

1. Go to developer.spotify.com/dashboard and create an app
2. In the app settings, add this as a Redirect URI: http://127.0.0.1:8888/callback
3. Copy your Client ID and Client Secret - you'll paste these into SoulSync's settings page

If you're accessing SoulSync from a different machine than where it's running (like a server), the Spotify OAuth callback can be tricky. Spotify redirects to 127.0.0.1 which points to your browser's machine, not the server. You have two options:

• When it redirects, manually change 127.0.0.1 in the URL bar to your server's IP, then hit enter
• Set up SSH port forwarding: ssh -L 8888:localhost:8888 user@your-server-ip, then do the auth from that terminal session

More detail in Support/DOCKER-OAUTH-FIX.md.

Step 3: Configure SoulSync

Open SoulSync at http://localhost:8008 (or your server's IP) and go to Settings.

slskd Connection:

• slskd URL: If both containers are on the same machine, use http://host.docker.internal:5030. If that doesn't work, use your machine's local IP like http://192.168.1.100:5030. Don't use localhost - that refers to inside the SoulSync container itself.
• API Key: Paste the API key you set up in slskd's config

Paths:

• Download Path: This should be the container path where slskd's downloads are mapped. If you followed the volume mapping above, that's /app/downloads
• Transfer Path: This is where SoulSync puts your organized/renamed music. The default is /app/Transfer - just make sure you have a volume mapping for it

Media Server (optional):

• Plex/Jellyfin/Navidrome URL: Use your machine's actual IP address, not localhost. For example http://192.168.1.100:32400 for Plex. Same reason as slskd - localhost inside Docker means the container, not your host machine.

Step 4: Docker Path Mapping

This is where most issues come from. The key concept: SoulSync runs inside a Docker container and can only see folders you explicitly map in. Paths inside the container are different from paths on your host machine.

What you need mapped:

What	Container Path	Host Path (your system)
Config	/app/config	Wherever you want config stored
Logs	/app/logs	Wherever you want logs stored
Database	/app/data	Use a named volume (see below)
slskd Downloads	/app/downloads	Same folder slskd downloads to
Music Library/Transfer	/app/Transfer	Where you want organized music to go

Example docker-compose volumes for Linux:

volumes:
  - ./config:/app/config
  - ./logs:/app/logs
  - soulsync_database:/app/data
  - /path/to/slskd/downloads:/app/downloads
  - /path/to/music/library:/app/Transfer

Example for Unraid:

volumes:
  - /mnt/user/appdata/soulsync/config:/app/config
  - /mnt/user/appdata/soulsync/logs:/app/logs
  - soulsync_database:/app/data
  - /mnt/user/Music/Downloads:/app/downloads
  - /mnt/user/Music/Library:/app/Transfer

Important: The database should use a named volume (soulsync_database:/app/data), not a direct host path mount. Mounting a host folder to /app/database will overwrite Python module files the app needs to run.

The paths you enter in SoulSync's settings page should always be the container paths (left side), not the host paths (right side). SoulSync doesn't know about your host filesystem - it only sees what's inside the container.

Unraid Users

If you're using the Unraid template from Community Applications, double check that the container path for your music share is set to match what SoulSync actually uses. The download folder should map to /app/downloads and your library/transfer folder should map to /app/Transfer. Then use those same container paths in SoulSync's settings page.

---

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

---