From 49d1cb595f8f3c4ec47319c839ad16be4f7b2a6c Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Thu, 12 Mar 2026 08:39:27 -0700 Subject: [PATCH] =?UTF-8?q?Update=20Help=20&=20Docs=20=E2=80=94=20add=20Qo?= =?UTF-8?q?buz=20everywhere,=20Tidal/Qobuz=20enrichment=20workers,=20fix?= =?UTF-8?q?=20Metadata=20Updater=20descriptions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- webui/static/docs.js | 35 ++++++++++++++++++++--------------- webui/static/script.js | 12 ++++++------ 2 files changed, 26 insertions(+), 21 deletions(-) diff --git a/webui/static/docs.js b/webui/static/docs.js index e7ee579d..7fdc7ec5 100644 --- a/webui/static/docs.js +++ b/webui/static/docs.js @@ -18,11 +18,11 @@ const DOCS_SECTIONS = [ content: () => `

Overview

-

SoulSync is a self-hosted music download, sync, and library management platform. It connects to Spotify, Apple Music/iTunes, Tidal, YouTube, and Beatport for metadata, and uses Soulseek (via slskd) as the primary download source. Your library is served through Plex, Jellyfin, or Navidrome.

+

SoulSync is a self-hosted music download, sync, and library management platform. It connects to Spotify, Apple Music/iTunes, Tidal, Qobuz, YouTube, and Beatport for metadata, and uses Soulseek (via slskd) as the primary download source. Your library is served through Plex, Jellyfin, or Navidrome.

-

🎵 Download Music

Search and download tracks in FLAC, MP3, and more from Soulseek, YouTube, or Tidal, with automatic metadata tagging and file organization.

+

🎵 Download Music

Search and download tracks in FLAC, MP3, and more from Soulseek, YouTube, Tidal, or Qobuz, with automatic metadata tagging and file organization.

🔄 Playlist Sync

Mirror playlists from Spotify, YouTube, Tidal, and Beatport. Discover official metadata and sync to your media server.

-

📚 Library Management

Browse, edit, and enrich your music library with metadata from 7 services. Write tags directly to audio files.

+

📚 Library Management

Browse, edit, and enrich your music library with metadata from 9 services. Write tags directly to audio files.

🤖 Automations

Schedule tasks, chain workflows with signals, and get notified via Discord, Pushbullet, or Telegram.

🔍 Artist Discovery

Discover new artists via similar-artist recommendations, seasonal playlists, genre exploration, and time-machine browsing.

👀 Watchlist

Follow artists and automatically scan for new releases. New tracks are added to your wishlist for download.

@@ -32,12 +32,12 @@ const DOCS_SECTIONS = [

First-Time Setup

After launching SoulSync, head to the Settings page to configure your services. At minimum you need:

    -
  1. Download Source — Connect at least one download source: Soulseek (slskd), YouTube, or Tidal. Soulseek offers the best quality selection; YouTube and Tidal work as alternatives or fallbacks in Hybrid mode.
    2. +
  2. Download Source — Connect at least one download source: Soulseek (slskd), YouTube, Tidal, or Qobuz. Soulseek offers the best quality selection; YouTube, Tidal, and Qobuz work as alternatives or fallbacks in Hybrid mode.
  3. Media Server — Connect Plex, Jellyfin, or Navidrome so SoulSync knows where your library lives and can trigger scans.
  4. Spotify (Recommended) — Connect Spotify for the richest metadata. Create an app at developer.spotify.com, enter your Client ID and Secret, then click Authenticate.
  5. Download Path — Set your download and transfer paths in the Download Settings section. The transfer path should point to your media server's monitored folder.
-
💡
You can start using SoulSync with just one download source (Soulseek, YouTube, or Tidal). Spotify and other services add metadata enrichment but aren't strictly required — iTunes/Apple Music is always available as a free fallback.
+
💡
You can start using SoulSync with just one download source (Soulseek, YouTube, Tidal, or Qobuz). Spotify and other services add metadata enrichment but aren't strictly required — iTunes/Apple Music is always available as a free fallback.

Connecting Services

@@ -49,7 +49,8 @@ const DOCS_SECTIONS = [ iTunes / Apple MusicFallback metadata source, always free, no auth neededNone Soulseek (slskd)Download source — P2P network, best for lossless and rare musicURL + API key YouTubeDownload source — audio extraction via yt-dlpNone (optional cookies browser) - TidalDownload source + playlist importOAuth — Client ID + Secret + TidalDownload source + playlist import + enrichmentOAuth — Client ID + Secret + QobuzDownload source + enrichmentUsername + Password (app ID auto-fetched) PlexMedia server — library scanning, metadata sync, audio streamingURL + Token JellyfinMedia server — library scanning, audio streamingURL + API Key NavidromeMedia server — auto-detects changes, audio streamingURL + Username + Password @@ -91,7 +92,7 @@ const DOCS_SECTIONS = [ - + @@ -313,6 +314,8 @@ const DOCS_SECTIONS = [

iTunes

iTunes/Apple Music IDs, preview links

Last.fm

Listener/play counts, bios, tags, similar artists for every artist/album/track

Genius

Lyrics, descriptions, alternate names, song artwork

+

Tidal

Tidal IDs, artist images, album labels, explicit flags, ISRCs

+

Qobuz

Qobuz IDs, artist images, album labels, genres, explicit flags

ℹ️
Workers retry "not found" items every 30 days and errored items every 7 days. You can pause/resume any worker from the dashboard.

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.

@@ -325,7 +328,7 @@ const DOCS_SECTIONS = [ - + @@ -366,7 +369,7 @@ const DOCS_SECTIONS = [
  • Quality Scanner — Scans your entire library and flags tracks below your quality preferences. Shows a breakdown of formats and bitrates, identifies tracks where higher-quality versions may be available, and automatically adds low-quality tracks to your wishlist for re-downloading at better quality.
  • Duplicate Cleaner — Identifies duplicate tracks by comparing title, artist, album, and duration. Lets you review duplicates and choose which version to keep (typically the higher-quality one). Frees disk space by removing redundant files.
  • Database Updater — Refreshes your library database by scanning your media server. Incremental mode only adds new content; Full Refresh rebuilds the entire database. Deep Scan performs a full comparison without losing any enrichment data from services.
    • -
  • Metadata Updater — Triggers all enrichment workers simultaneously with reset flags, forcing them to re-check every item in your library against all connected services (MusicBrainz, Spotify, iTunes, Last.fm, Deezer, AudioDB, Genius). Useful after connecting a new service or when metadata seems incomplete.
    • +
  • Metadata Updater — Triggers all enrichment workers simultaneously with reset flags, forcing them to re-check every item in your library against all connected services (MusicBrainz, Spotify, iTunes, Last.fm, Deezer, AudioDB, Genius, Tidal, Qobuz). Useful after connecting a new service or when metadata seems incomplete.
  • Repair Worker — Background service that scans recently downloaded folders and repairs track metadata. It reads album IDs from file tags, fetches official tracklists from Spotify or MusicBrainz, and fixes incorrect or missing track numbers. Runs automatically after batch downloads complete and can be paused/resumed from the dashboard.
    • @@ -509,10 +512,11 @@ const DOCS_SECTIONS = [ +
    FolderDefault (Docker)Purpose
    Download Path/app/downloadsWhere slskd/YouTube/Tidal initially saves downloaded files. This is a temporary staging area — files should not stay here permanently.
    Download Path/app/downloadsWhere slskd/YouTube/Tidal/Qobuz initially saves downloaded files. This is a temporary staging area — files should not stay here permanently.
    Transfer Path/app/TransferWhere post-processed files are moved after tagging and renaming. This must be the folder your media server (Plex/Jellyfin/Navidrome) monitors.
    Staging Path/app/StagingFor the Import feature only. Drop audio files here to import them into your library via the Import page.
    ToolWhat It Does
    Database UpdaterRefreshes your library by scanning your media server. Choose incremental (new only) or full refresh.
    Metadata UpdaterUpdates artist photos, genres, styles, and biographies from MusicBrainz, Spotify, iTunes, and Last.fm.
    Metadata UpdaterTriggers all 9 enrichment workers to re-check your library against all connected services.
    Quality ScannerScans library for tracks below your quality preferences. Shows how many meet standards and finds replacements.
    Duplicate CleanerIdentifies and removes duplicate tracks from your library, freeing up disk space.
    Discovery PoolView and fix matched/failed discovery results across all mirrored playlists.
    SoulseekP2P network via slskd — largest selection of lossless and rare musicFLAC, rare tracks, DJ sets
    YouTubeYouTube audio extraction via yt-dlpLive performances, remixes, tracks not on Soulseek
    TidalTidal HiFi streaming rip (requires auth)Guaranteed quality, official releases
    QobuzQobuz Hi-Res streaming rip (requires auth)Audiophile quality, up to 24-bit/192kHz
    HybridTries your primary source first, then automatically falls back to alternatesBest overall success rate
    -
    💡
    Hybrid mode is recommended for most users. It tries Soulseek first (best quality), then falls back to YouTube or Tidal if no suitable results are found. The fallback order respects your quality profile settings.
    +
    💡
    Hybrid mode is recommended for most users. It tries Soulseek first (best quality), then falls back to YouTube, Tidal, or Qobuz if no suitable results are found. The fallback order and priority are configurable via drag-and-drop in Settings.

    YouTube settings include cookies browser selection (for bot detection bypass), download delay (seconds between requests), and minimum confidence threshold for title matching.

    @@ -647,7 +651,7 @@ const DOCS_SECTIONS = [
  • Filter by category, content type (live/compilations/featured), or status (owned/missing)
  • Click any release to open the download modal with track selection
    • -

    At the top, View on buttons link to the artist on each matched external service (Spotify, Apple Music, MusicBrainz, Deezer, AudioDB, Last.fm, Genius). Service badges on artist cards also indicate which services have matched this artist.

    +

    At the top, View on buttons link to the artist on each matched external service (Spotify, Apple Music, MusicBrainz, Deezer, AudioDB, Last.fm, Genius, Tidal, Qobuz). Service badges on artist cards also indicate which services have matched this artist.

    Similar Artists appear as clickable bubbles below the discography for further exploration and discovery.

    @@ -834,7 +838,7 @@ const DOCS_SECTIONS = [ content: () => `

    Standard View

    -

    The Library page shows all artists in your collection as cards with images, album/track counts, and service badges (Spotify, MusicBrainz, Deezer, AudioDB, iTunes, Last.fm, Genius) indicating which services have matched this artist.

    +

    The Library page shows all artists in your collection as cards with images, album/track counts, and service badges (Spotify, MusicBrainz, Deezer, AudioDB, iTunes, Last.fm, Genius, Tidal, Qobuz) indicating which services have matched this artist.

    Use the search bar, alphabet navigation (A–Z, #), and watchlist filter (All/Watched/Unwatched) to browse. Click any artist card to view their discography.

    The artist detail page shows albums, EPs, and singles as cards with completion percentages. Filter by category, content type (live/compilations/featured), or status (owned/missing). At the top, View on buttons link to the artist on each matched external service.

    @@ -852,7 +856,7 @@ const DOCS_SECTIONS = [

    Service Matching

    -

    In the Enhanced view, each artist, album, and track shows match status chips for all 7 services. Click any chip to manually search and link the correct external ID. Run per-service enrichment from the dropdown to pull in metadata from a specific source.

    +

    In the Enhanced view, each artist, album, and track shows match status chips for all 9 services. Click any chip to manually search and link the correct external ID. Run per-service enrichment from the dropdown to pull in metadata from a specific source.

    Matched services show as clickable badges linking to the entity on that service's website.

    @@ -1007,6 +1011,7 @@ const DOCS_SECTIONS = [
  • Tidal — Client ID + Secret, then Authenticate via OAuth
  • Last.fm — API key from last.fm/api
  • Genius — Access token from genius.com/api-clients
    • +
  • Qobuz — Username + Password (app ID is auto-fetched)
  • AcoustID — API key from acoustid.org (enables fingerprint verification)
  • ListenBrainz — Base URL + token for listening history and playlist import
    • @@ -1028,7 +1033,7 @@ const DOCS_SECTIONS = [

    Download Settings

      -
    • Download Source Mode — Soulseek, YouTube, Tidal, or Hybrid. Hybrid tries your primary source first, then falls back to alternates. See Download Sources in the Music Downloads section for details.
      • +
    • Download Source Mode — Soulseek, YouTube, Tidal, Qobuz, or Hybrid. Hybrid tries your primary source first, then falls back to alternates with configurable priority via drag-and-drop. See Download Sources in the Music Downloads section for details.
    • Download Path — The folder where files are initially downloaded. This must match the folder your download source (slskd) writes to. In Docker, this is the container-side mount point (e.g., /app/downloads), not the host path. SoulSync monitors this folder for completed downloads to begin post-processing.
    • Transfer Path — The final destination for processed music files. After tagging, renaming, and organizing, files are moved here. This must point to your media server's monitored music folder (the folder Plex/Jellyfin/Navidrome watches for new content). In Docker, use the container-side path (e.g., /app/Transfer).
    • Staging Path — Folder for the Import feature (files placed here appear on the Import page). Separate from the download/transfer pipeline.
      • @@ -1176,7 +1181,7 @@ const DOCS_SECTIONS = [ download_progressPer-track download progress (speed, ETA, percentage) download_completeTrack finished downloading and post-processing batch_progressAlbum/playlist batch download status - worker_statusEnrichment worker status (Spotify, MusicBrainz, Deezer, etc.) + worker_statusEnrichment worker status (Spotify, MusicBrainz, Deezer, Tidal, Qobuz, etc.) scan_progressLibrary scan, quality scan, or duplicate scan progress system_statusService connectivity changes (Spotify rate limit, slskd disconnect) activitySystem activity feed entries diff --git a/webui/static/script.js b/webui/static/script.js index eadc3147..fbd4fff9 100644 --- a/webui/static/script.js +++ b/webui/static/script.js @@ -17388,7 +17388,7 @@ const TOOL_HELP_CONTENT = { title: 'Metadata Updater', content: `

      What does this tool do?

      -

      The Metadata Updater enhances your library by fetching artist photos, genres, and album artwork from Spotify.

      +

      The Metadata Updater triggers all enrichment workers simultaneously, re-checking every item in your library against all connected services (Spotify, MusicBrainz, iTunes, Deezer, AudioDB, Last.fm, Genius, Tidal, Qobuz).

      Refresh Interval Options

        @@ -17400,14 +17400,14 @@ const TOOL_HELP_CONTENT = {

        What gets updated?

          -
        • Artist profile photos
          • -
        • Music genres
          • -
        • Album cover artwork
          • -
        • Spotify popularity scores
          • +
        • Artist profile photos, genres, and descriptions
          • +
        • Album cover artwork, labels, and release info
          • +
        • Track ISRCs, explicit flags, and external IDs
          • +
        • Service match status for all 9 enrichment workers

        Note

        -

        This tool is only available for Plex media servers. It requires Spotify authentication to fetch metadata.

        +

        Available for Plex and Jellyfin media servers. Each enrichment worker only runs if its service is authenticated.

        ` }, 'quality-scanner': {