Version & Updates: Click the version number in the sidebar footer to open the What's New modal, which shows detailed release notes for every feature and fix. SoulSync automatically checks for updates by comparing your running version against the latest GitHub commit. If an update is available, a banner appears in the modal. Docker users are notified when a new image has been pushed to the repo.
+SoulSync runs in Docker with the following environment variables:
+| Variable | Default | Description |
|---|---|---|
DATABASE_PATH | ./database | Directory where the SQLite database is stored. Mount a volume here to persist data across container restarts. |
SOULSYNC_CONFIG_PATH | ./config | Directory where config.json and the encryption key are stored. Mount a volume here to persist settings. |
SOULSYNC_COMMIT_SHA | (auto) | Baked in at Docker build time. Used for update detection — compares against GitHub's latest commit. |
Key volume mounts: Map your download path, transfer path (media server's monitored folder), and staging path to host directories. Ensure the paths configured in SoulSync Settings match the container-side mount points.
+Podman / Rootless Docker: SoulSync supports Podman rootless (keep-id) and rootless Docker setups. The entrypoint handles permission alignment automatically.
+Config migration: When upgrading from older versions, SoulSync automatically migrates settings from config.json to the database on first startup. No manual migration is needed.
Lyrics, descriptions, alternate names, song artwork
Rate Limit Protection: Workers include smart rate limiting for all APIs. If Spotify returns a rate limit (429), a global ban activates — all Spotify calls are suppressed and searches automatically fall back to iTunes. A countdown modal appears showing ban duration, and the worker auto-resumes when the ban expires. You can manually disconnect Spotify from the modal to clear the ban immediately.
+Rate Limit Protection: Workers include smart rate limiting for all APIs. If Spotify returns a rate limit with a Retry-After greater than 60 seconds, a global ban activates — all Spotify API calls are suppressed before they're made, and searches automatically fall back to iTunes/Apple Music. A countdown modal appears showing the ban duration, triggering endpoint, and remaining time. The enrichment worker auto-pauses during the ban and resumes when it expires.
+The rate limit modal provides a Disconnect Spotify button that immediately clears the ban, pauses the Spotify enrichment worker, and deletes the local Spotify cache. This lets you switch to Apple Music as your primary metadata source without waiting for the ban to expire.
Additional maintenance tools accessible from the dashboard:
Export any mirrored playlist as an M3U file for use in external media players or media servers. Enable M3U export in Settings and use the export button on any playlist card.
-M3U files reference the actual file paths in your library, so they work with any M3U-compatible player. Auto-save can be enabled to regenerate M3U files automatically when playlists are updated.
+M3U files reference the actual file paths in your library, so they work with any M3U-compatible player.
+Auto-Save — When enabled in Settings, M3U files are automatically regenerated every time a playlist is synced or updated. Manual Export — The export button on any playlist modal creates an M3U file on demand, even when auto-save is disabled.
Downloads can be started from multiple places: Enhanced Search results, artist discography, Download Missing modal, wishlist auto-processing, and playlist sync.
+Download Candidate Selection: If a download fails or no suitable source is found, you can view the cached search candidates and manually pick an alternative file from a different user. This lets you recover failed downloads without restarting the entire search.
Each playlist can be played in the media player, downloaded, or synced to your media server. Genre browsers let you filter discovery pool content by specific genres.
+Each playlist can be played in the media player, downloaded, or synced to your media server.
+Genre Browser — Filter discovery pool content by specific genres. Browse available genres and view top tracks within each genre category.
+ListenBrainz Playlists — If ListenBrainz is configured, the Discover page also shows personalized playlists generated from your listening history: Created For You, Your Playlists, and Collaborative playlists.
Auto-Processing: The system automation runs every 30 minutes, picking up wishlist items and attempting to download them from your configured source. Failed items are retried with increasing backoff.
+Auto-Processing: The system automation runs every 30 minutes, picking up wishlist items and attempting to download them from your configured source. Processing alternates between album and singles cycles — one run processes albums, the next run processes singles. If one category is empty, it automatically switches to the other. Failed items are retried with increasing backoff.
Manual Processing: Use the Process Wishlist automation action to trigger processing on demand. Options include processing all items, albums only, or singles only.
Cleanup: The Cleanup Wishlist action removes duplicates (same track added multiple times) and items you already own in your library.
Each automation card shows its last run time and run count. For scheduled automations, a countdown timer shows when the next run will occur.
-Use the Run Now button on any automation card to execute it immediately, regardless of its schedule. The result (success/failure) updates in real-time on the card.
+Use the Run Now button on any automation card to execute it immediately, regardless of its schedule. The result (success/failure) updates in real-time on the card. Running automations display a glow effect on their card.
+Stall detection: If an automation action runs for more than 2 hours without completing, it is automatically flagged as stalled and terminated to prevent resource leaks.
The Dashboard activity feed also logs every automation execution with timestamps, so you can review the full history of what ran and when.
Toggle Enhanced on any artist's detail page to access the professional library management tool:
+Toggle Enhanced on any artist's detail page to access the professional library management tool. This view is admin-only — non-admin profiles see the Standard view only.
Media Session API — SoulSync integrates with your OS media controls (lock screen, system tray) for play/pause, next/previous, and seek.
@@ -778,7 +811,7 @@ const DOCS_SECTIONS = [ content: () => `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. Each service has a Test Connection button to verify your credentials are working.
+Configure credentials for each external service. All fields are saved to your local database and encrypted at rest using a Fernet key generated on first launch. Nothing is sent to external servers except during actual API calls. Each service has a Test Connection button to verify your credentials are working.
The media player streams audio directly from your connected server — tracks play through your Plex, Jellyfin, or Navidrome instance without needing local file access.
+sk_ prefix and are shown once at creation — only a SHA-256 hash is stored for security.Artist/Album/TrackNum - Title.extShared across all profiles: Music library (files and metadata), service credentials, settings, and automations.
Admins can control what each profile has access to. When creating or editing a non-admin profile:
+If the admin removes a page that was set as a user's home page, the home page automatically resets. Navigation guards prevent users from accessing restricted pages even via direct URL or browser history.
+Each user can choose which page they land on when they log in:
+POST /api/database/backupThe full API has 90+ endpoints covering library, downloads, playlists, automations, settings, and more. Use a reverse proxy (Nginx, Caddy, Traefik) for external access with HTTPS.
+The full API has 200+ endpoints covering library, downloads, playlists, automations, profiles, settings, and more. Use a reverse proxy (Nginx, Caddy, Traefik) for external access with HTTPS.