From 54b02b86c14f01fa929c3057e0d35ffbbd92f3d3 Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Tue, 24 Mar 2026 12:30:26 -0700 Subject: [PATCH] Update help docs: add HiFi/Deezer sources, quality fallback, template vars - Overview and setup sections now list all 6 download sources - Services table adds HiFi (no auth) and Deezer (ARL token) - Enhanced Search documents multi-source tabs (Spotify/iTunes/Deezer) - Download Sources table adds HiFi and Deezer rows - Post-processing explains AcoustID skip for streaming sources and the new artist/title verification for streaming candidates - File Organization documents $albumtype, $disc, and all template vars - Quality Profiles adds callout for per-source fallback toggle - Settings credentials list adds HiFi and Deezer entries --- webui/static/docs.js | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/webui/static/docs.js b/webui/static/docs.js index eaa3190f..359eea04 100644 --- a/webui/static/docs.js +++ b/webui/static/docs.js @@ -45,10 +45,10 @@ 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, 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.

+

SoulSync is a self-hosted music download, sync, and library management platform. It connects to Spotify, Apple Music/iTunes, Deezer, Tidal, Qobuz, YouTube, and Beatport for metadata, and downloads from Soulseek, YouTube, Tidal, Qobuz, HiFi, and Deezer. Your library is served through Plex, Jellyfin, or Navidrome.

${docsImg('gs-overview.jpg', 'SoulSync dashboard overview')}
-

🎵 Download Music

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

+

🎵 Download Music

Search and download tracks in FLAC, MP3, and more from 6 sources (Soulseek, YouTube, Tidal, Qobuz, HiFi, Deezer), 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 9 services. Write tags directly to audio files.

🤖 Automations

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

@@ -60,13 +60,13 @@ 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, Tidal, or Qobuz. Soulseek offers the best quality selection; YouTube, Tidal, and Qobuz work as alternatives or fallbacks in Hybrid mode.
    2. +
  2. Download Source — Connect at least one download source: Soulseek (slskd), YouTube, Tidal, Qobuz, HiFi, or Deezer. Soulseek offers the best quality selection; the others 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.
${docsImg('gs-first-setup.jpg', 'Settings page first-time setup')} -
💡
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.
+
💡
You can start using SoulSync with just one download source. Spotify and other services add metadata enrichment but aren't strictly required — iTunes/Apple Music and Deezer are always available as free fallbacks.

Connecting Services

@@ -80,6 +80,8 @@ const DOCS_SECTIONS = [ YouTubeDownload source — audio extraction via yt-dlpNone (optional cookies browser) TidalDownload source + playlist import + enrichmentOAuth — Client ID + Secret QobuzDownload source + enrichmentUsername + Password (app ID auto-fetched) + HiFiDownload source — free lossless via community APINone + DeezerDownload source + metadata fallbackARL cookie token 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 @@ -668,12 +670,13 @@ const DOCS_SECTIONS = [ content: () => `

Enhanced Search

-

The default search mode. Type an artist, album, or track name and results appear in a categorized dropdown: In Your Library, Artists, Albums, Singles & EPs, and Tracks. Results come from Spotify (or iTunes if Spotify is unavailable).

+

The default search mode. Type an artist, album, or track name and results appear in a categorized dropdown: In Your Library, Artists, Albums, Singles & EPs, and Tracks. Results come from your primary metadata source (Spotify by default).

  • Click an artist to view their full discography with download buttons on each release
  • Click an album to open the download modal with track selection
    • -
  • Click a track to search Soulseek for that specific song
    • +
  • Click a track to search your download source for that specific song
  • Preview tracks — Play button on search result tracks lets you stream a preview directly from your download source before committing to a download
    • +
  • Multi-source tabs — Switch between metadata sources (Spotify, iTunes, Deezer) using tabs above the results. Each source returns its own catalog, so tracks missing on one may be found on another
${docsImg('dl-enhanced-search.jpg', 'Enhanced search results')}
@@ -693,10 +696,12 @@ const DOCS_SECTIONS = [ 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 + HiFiFree lossless downloads via community-run API instancesNo account needed, good FLAC availability + DeezerDeezer streaming rip via ARL token (FLAC/MP3)Large catalog, easy setup, FLAC with HiFi sub 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, Tidal, or Qobuz if no suitable results are found. The fallback order and priority are configurable via drag-and-drop in Settings.
+
💡
Hybrid mode is recommended for most users. It tries your primary source first, then falls back through your configured priority order. All six sources (Soulseek, YouTube, Tidal, Qobuz, HiFi, Deezer) can be ordered 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.

@@ -715,10 +720,10 @@ const DOCS_SECTIONS = [

Post-Processing Pipeline

After a file is downloaded, it goes through an automatic pipeline before appearing in your library:

    -
  1. AcoustID Fingerprint Verification — If AcoustID is configured, the downloaded file is fingerprinted and compared against the expected track. Title and artist are fuzzy-matched (title ≥ 70% similarity, artist ≥ 60%). Files that fail verification are quarantined instead of added to your library.
    2. +
  2. AcoustID Fingerprint Verification — If AcoustID is configured, the downloaded file is fingerprinted and compared against the expected track. Title and artist are fuzzy-matched (title ≥ 70% similarity, artist ≥ 60%). Files that fail verification are quarantined instead of added to your library. Note: AcoustID is skipped for streaming sources (Tidal, Qobuz, Deezer, HiFi) since files are downloaded by exact track ID. However, streaming search results are still verified by artist and title matching before download to prevent wrong-track matches (e.g. same title, different artist).
  3. Metadata Tagging — The file is tagged with official metadata: title, artist, album artist, album, track number, disc number, year, genre, and composer. Tags are written using Mutagen (supports MP3, FLAC, OGG, M4A).
  4. Cover Art Embedding — Album artwork is downloaded from the metadata source and embedded directly into the audio file.
    5. -
  5. File Organization — The file is renamed and moved to your transfer path following the template: Artist/Album/TrackNum - Title.ext. For multi-disc albums, a Disc N/ subfolder is automatically created when the album has more than one disc.
    6. +
  6. File Organization — The file is renamed and moved to your transfer path following customizable templates. Separate templates for albums, singles, and playlists are configured in Settings. Available variables include $artist, $album, $title, $track, $year, $quality, and $albumtype (resolves to Album, Single, EP, or Compilation). For multi-disc albums, a Disc N/ subfolder is automatically created when the album has more than one disc (or use $disc in your template for manual control).
  7. Lyrics (LRC) — Synced lyrics are fetched from the LRClib API and saved as .lrc sidecar files alongside the audio file. Compatible media players (foobar2000, MusicBee, Plex, etc.) will display time-synced lyrics automatically. Falls back to plain-text lyrics if synced versions aren't available.
  8. Lossy Copy — If enabled in settings, a lower-bitrate copy is created alongside the original (useful for mobile device syncing).
  9. Media Server Scan — Your media server (Plex/Jellyfin) is notified to scan for the new file. Navidrome auto-detects changes.
    10. @@ -738,6 +743,7 @@ const DOCS_SECTIONS = [

    Each format has configurable bitrate ranges and a priority order. Enable Fallback to accept any quality when preferred formats aren't available.

    +
    💡
    Streaming source quality: Tidal, Qobuz, HiFi, and Deezer each have their own quality dropdown in Settings. By default, if your preferred quality isn't available for a track, the source falls back to the next lower tier (e.g. FLAC → AAC 320). Disable Allow quality fallback next to the quality dropdown to enforce strict quality — the source will skip tracks it can't deliver at your chosen quality, and the orchestrator will try the next source in your priority list.
    ${docsImg('dl-quality-profiles.jpg', 'Quality profile settings')}
@@ -1221,6 +1227,8 @@ const DOCS_SECTIONS = [
  • Last.fm — API key from last.fm/api
  • Genius — Access token from genius.com/api-clients
  • Qobuz — Username + Password (app ID is auto-fetched)
    • +
  • HiFi — No credentials needed, uses community-run API instances. Test Connection to verify.
    • +
  • Deezer — ARL cookie token from your browser (log into deezer.com → DevTools → Cookies → copy arl)
  • AcoustID — API key from acoustid.org (enables fingerprint verification)
  • ListenBrainz — Base URL + token for listening history and playlist import
    • @@ -1243,7 +1251,7 @@ const DOCS_SECTIONS = [

    Download Settings

      -
    • 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 Source Mode — Soulseek, YouTube, Tidal, Qobuz, HiFi, Deezer, or Hybrid. Hybrid tries your primary source first, then falls back to alternates with configurable priority via drag-and-drop. Each streaming source has its own quality dropdown and an Allow quality fallback toggle. See Download Sources and Quality Profiles 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.