From 4560256bfe9e44c6dff527c6f8754142b1c9b72d Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Sat, 11 Apr 2026 23:26:01 -0700 Subject: [PATCH] Add informative help text and tips to every setup wizard step Each step now explains what it does and how it connects to the rest of SoulSync. Metadata step explains catalog vs download source. Download step explains the search-match-download pipeline and Hybrid mode. Paths step explains the two-folder system. Watchlist step explains Discover page, scanner schedule, and per-artist filters. First Download step explains the full tagging and organization pipeline. Done page adds a 2x3 tips grid covering Sync, Wishlist, Automations, Notifications, Interactive Help, and Settings. --- webui/static/setup-wizard.css | 62 ++++++++++++++++++++++++++++ webui/static/setup-wizard.js | 77 +++++++++++++++++++++++++++++++---- 2 files changed, 130 insertions(+), 9 deletions(-) diff --git a/webui/static/setup-wizard.css b/webui/static/setup-wizard.css index 8ce2ea4f..1e3939b0 100644 --- a/webui/static/setup-wizard.css +++ b/webui/static/setup-wizard.css @@ -690,6 +690,64 @@ font-weight: 600; } +/* ---- Info Tip Boxes ---- */ +.setup-info-box { + padding: 14px 16px; + background: rgba(var(--accent-rgb), 0.06); + border: 1px solid rgba(var(--accent-rgb), 0.15); + border-radius: 10px; + margin-bottom: 16px; + font-size: 0.82rem; + color: rgba(255, 255, 255, 0.6); + line-height: 1.55; +} + +.setup-info-box strong { + color: rgba(255, 255, 255, 0.85); + font-weight: 600; +} + +.setup-info-box ul { + margin: 6px 0 0 16px; + padding: 0; +} + +.setup-info-box ul li { + margin-bottom: 4px; +} + +.setup-info-box + .setup-info-box { + margin-top: -4px; +} + +/* ---- Done Page Tips ---- */ +.setup-tips-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 10px; + margin-bottom: 20px; +} + +.setup-tip-card { + padding: 14px; + background: rgba(255, 255, 255, 0.03); + border: 1px solid rgba(255, 255, 255, 0.06); + border-radius: 10px; +} + +.setup-tip-title { + font-size: 0.82rem; + font-weight: 600; + color: rgba(255, 255, 255, 0.85); + margin-bottom: 6px; +} + +.setup-tip-text { + font-size: 0.78rem; + color: rgba(255, 255, 255, 0.45); + line-height: 1.5; +} + /* ---- Loading Spinner ---- */ .setup-spinner { display: inline-block; @@ -729,4 +787,8 @@ .setup-step-line { width: 20px; } + + .setup-tips-grid { + grid-template-columns: 1fr; + } } diff --git a/webui/static/setup-wizard.js b/webui/static/setup-wizard.js index 6866e8bb..5ffd0c80 100644 --- a/webui/static/setup-wizard.js +++ b/webui/static/setup-wizard.js @@ -214,27 +214,34 @@ function _renderWelcome(el) {
- Search and download music from multiple sources + Search and download music from 6 sources — Soulseek, YouTube, Tidal, Qobuz, HiFi, and Deezer
- Sync playlists from Spotify, Tidal, Deezer and more + Mirror playlists from Spotify, Tidal, Deezer, YouTube, Beatport, and ListenBrainz
- Discover new music with watchlist monitoring and smart caching + Watch artists and auto-download new releases as they drop
- Organize and serve to Plex, Jellyfin, or Navidrome + Organize your library and serve to Plex, Jellyfin, or Navidrome +
+
+
+ +
+ Build automations that scan, download, and notify on your schedule
+

This wizard will walk you through the essentials. Everything can be changed later in Settings.

@@ -254,6 +261,9 @@ function _renderMetadata(el) {

Metadata Source

Where should SoulSync look up track info, album art, and metadata?

+
+ What is a metadata source? When you search for music or sync a playlist, SoulSync needs a catalog to look up track names, artists, album art, track numbers, and release dates. This source provides that information — it does not affect where music is downloaded from. +
${sources.map(s => `

Download Source

-

Choose your primary download source. You can enable Hybrid mode later in Settings to try multiple sources automatically.

+

Choose where SoulSync downloads music files from.

+
+ How downloads work: When you search for a track, SoulSync uses your metadata source to identify it, then searches your download source for the actual audio file. The matching engine automatically finds the best quality match. +

+ Hybrid mode (available later in Settings) lets you set a priority order — if your primary source doesn't have a track, SoulSync automatically tries the next source in line. +
${sources.map(s => `

Paths & Media Server

Where should downloaded music go?

+
+ Two-folder system: Music downloads to the Download Folder first as raw files. After post-processing (metadata tagging, file organization), finished tracks are moved to the Transfer Folder organized into Artist/Album subfolders. Point your media server at the Transfer folder. +
@@ -515,7 +533,10 @@ function _renderPaths(el) {
-

Connect a media server

+

Connect a media server

+
+ Connecting a media server lets SoulSync trigger library scans after downloads, import your existing library, and display what you already own when searching. Select None if you don't use one. +
${['plex', 'jellyfin', 'navidrome', 'none'].map(s => `

Add Your First Artists

-

Search for artists to add to your watchlist. SoulSync will automatically download their new releases.

+

Search for artists to add to your watchlist.

+
+ What is the Watchlist? Artists on your watchlist are monitored for new releases. When a watched artist drops a new album, EP, or single, it appears on your Discover page and can be auto-downloaded. +
    +
  • Discover page — populated by new releases from watched artists, similar artists, and seasonal picks
    • +
  • Watchlist Scanner — runs automatically on a schedule to check for new releases
    • +
  • Filters — per-artist controls for albums, EPs, singles, remixes, live recordings, and more
    • +
+ You can always add or remove artists later from the Artists page. +
${chips}
@@ -737,7 +767,10 @@ function _renderFirstDownload(el) { el.innerHTML = `

Your First Download

-

Search for a track and download it to see SoulSync in action.

+

Try searching for a track to see the full pipeline in action.

+
+ How it works: Type a song name below. SoulSync searches your metadata source for the track, then finds the best matching audio file from your download source. The track is tagged with full metadata (artist, album, track number, artwork) and organized into your Transfer folder. +
@@ -916,7 +949,7 @@ function _renderDone(el) {

You're All Set!

-

SoulSync is configured and ready to go.

+

SoulSync is configured and ready to go. Here's a quick overview of what's available.

${summaryRows.map(r => `
@@ -925,6 +958,32 @@ function _renderDone(el) {
`).join('')}
+
+
+
Sync Page
+
Mirror playlists from Spotify, Tidal, Deezer, YouTube, Beatport, and ListenBrainz. SoulSync matches and downloads missing tracks automatically.
+
+
+
Wishlist
+
Tracks that can't be found are saved to your Wishlist and retried automatically. Check it on the Dashboard to see what's pending.
+
+
+
Automations
+
Build event-driven workflows: scan watchlists, process wishlists, sync playlists on a schedule, and get notified via Discord, Telegram, or Pushbullet.
+
+
+
Notifications
+
The bell icon (top-right) shows download completions, new releases, sync results, and errors. Configure external alerts in Settings.
+
+
+
Interactive Help
+
Click the ? button (bottom-right) anytime for context-aware help. It explains any section of the UI you click on.
+
+
+
Settings
+
Everything from this wizard plus much more — file organization templates, quality preferences, tag embedding, and advanced options.
+
+
`;