From efe8280e234e3edab377ce98bbc7878ef307febd Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Sat, 18 Apr 2026 17:35:20 -0700 Subject: [PATCH] =?UTF-8?q?Rebrand=20folder=20terminology:=20Download?= =?UTF-8?q?=E2=86=92Input,=20Transfer=E2=86=92Output,=20Staging=E2=86=92Im?= =?UTF-8?q?port?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All user-facing labels, docs, help text, tooltips, error messages, and debug info output updated. Backend config keys, variable names, actual path values, and Docker volume mounts are completely unchanged — zero functional impact. --- README.md | 12 ++-- docker-compose.yml | 4 +- web_server.py | 28 ++++----- webui/index.html | 24 ++++---- webui/static/docs.js | 112 +++++++++++++++++------------------ webui/static/helper.js | 38 ++++++------ webui/static/script.js | 26 ++++---- webui/static/setup-wizard.js | 10 ++-- 8 files changed, 127 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index bacabd48..6d1c30c9 100644 --- a/README.md +++ b/README.md @@ -280,9 +280,9 @@ Open SoulSync at `http://localhost:8008` and go to Settings. **Download Source**: Choose your preferred source (Soulseek, Deezer, Tidal, Qobuz, HiFi, YouTube, or Hybrid) **Paths**: -- **Download Path**: Container path to slskd's download folder (e.g., `/app/downloads`) -- **Transfer Path**: Where organized music goes (e.g., `/app/Transfer`) -- **Staging Path**: Optional import folder (e.g., `/app/Staging`) +- **Input Folder**: Container path to slskd's download folder (e.g., `/app/downloads`) +- **Output Folder**: Where organized music goes (e.g., `/app/Transfer`) +- **Import Folder**: Optional folder for importing existing music (e.g., `/app/Staging`) **Media Server** (optional): Use your machine's actual IP (not `localhost` — that means inside the container) @@ -293,9 +293,9 @@ Open SoulSync at `http://localhost:8008` and go to Settings. | Config | `/app/config` | Your config folder | | Logs | `/app/logs` | Your logs folder | | Database | `/app/data` | Named volume (recommended) | -| Downloads | `/app/downloads` | Same folder slskd downloads to | -| Transfer | `/app/Transfer` | Where organized music goes | -| Staging | `/app/Staging` | Optional import folder | +| Input | `/app/downloads` | Same folder slskd downloads to | +| Output | `/app/Transfer` | Where organized music goes | +| Import | `/app/Staging` | Optional folder for importing music | **Important:** Use a named volume for the database (`soulsync_database:/app/data`). Direct host path mounts to `/app/data` can overwrite Python module files. diff --git a/docker-compose.yml b/docker-compose.yml index cafa2e54..a2d8a0d4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -39,13 +39,13 @@ services: # Use named volume for database persistence (separate from host database) # NOTE: Changed from /app/database to /app/data to avoid overwriting Python package - soulsync_database:/app/data - # IMPORTANT: Mount host paths that your download/transfer folders live on. + # IMPORTANT: Mount host paths that your input/output folders live on. # Replace these examples with your actual paths: # Linux/Mac: - /path/to/your/downloads:/host/downloads:rw # WSL: - /mnt/d/Music:/host/music:rw # You can add as many mounts as needed for your setup. # - /path/to/downloads:/host/downloads:rw - # - /path/to/transfer:/host/transfer:rw + # - /path/to/music-library:/host/music:rw # Optional: Mount your music library for Plex/Jellyfin/Navidrome access # - /path/to/your/music:/music:ro extra_hosts: diff --git a/web_server.py b/web_server.py index 240a2c1d..af156f14 100644 --- a/web_server.py +++ b/web_server.py @@ -1727,7 +1727,7 @@ def _register_automation_handlers(): log_line=f'Empty directories: removed {dirs_removed}', log_type='success' if dirs_removed else 'info') # --- 4. Sweep empty staging directories --- - _update_automation_progress(automation_id, phase='Sweeping staging folder...', progress=60) + _update_automation_progress(automation_id, phase='Sweeping import folder...', progress=60) staging_path = _get_staging_path() s_removed = 0 if os.path.isdir(staging_path): @@ -4454,9 +4454,9 @@ def run_service_test(service, test_config): count += 1 if count > 100: break # Don't count everything, just confirm files exist - return True, f"SoulSync standalone ready! Transfer folder: {transfer_path} ({count}+ audio files)" + return True, f"SoulSync standalone ready! Output folder: {transfer_path} ({count}+ audio files)" else: - return False, f"Transfer folder not found: {transfer_path}" + return False, f"Output folder not found: {transfer_path}" elif service == "soulseek": if soulseek_client is None: return False, "Download orchestrator failed to initialize. Check server logs for startup errors." @@ -6852,7 +6852,7 @@ def get_automation_blocks(): {"type": "clean_completed_downloads", "label": "Clean Completed Downloads", "icon": "check-square", "description": "Clear completed downloads and empty directories", "available": True}, {"type": "full_cleanup", "label": "Full Cleanup", "icon": "trash", - "description": "Clear quarantine, download queue, staging folder, and search history in one sweep", "available": True}, + "description": "Clear quarantine, download queue, import folder, and search history in one sweep", "available": True}, {"type": "deep_scan_library", "label": "Deep Scan Library", "icon": "search", "description": "Full library comparison without losing enrichment data", "available": True}, {"type": "run_script", "label": "Run Script", "icon": "terminal", @@ -22516,7 +22516,7 @@ def get_version_info(): }, { "title": "Auto-Import", - "description": "Background staging folder watcher that automatically identifies and imports music into your library", + "description": "Background import folder watcher that automatically identifies and imports music into your library", "features": [ "• Recursive scan — any folder depth (Artist/Album/tracks, Album/tracks, loose files)", "• Single file support — loose audio files identified via tags, filename, or AcoustID", @@ -22526,7 +22526,7 @@ def get_version_info(): "• Expandable track match details with per-track confidence scores", "• Race condition fix prevents duplicate processing during multi-track albums", ], - "usage_note": "Enable on the Import page Auto tab. Set your staging folder in Settings." + "usage_note": "Enable on the Import page Auto tab. Set your import folder in Settings." }, { "title": "Wishlist Nebula", @@ -22982,7 +22982,7 @@ _OLD_V22_NOTES = """ "title": "Fix Library Maintenance Path Fixes Failing Silently", "description": "Path mismatch fixes now use fresh config and report errors to the UI", "features": [ - "• Transfer folder path is re-read from config before each fix attempt", + "• Output folder path is re-read from config before each fix attempt", "• Fix failure reasons are now shown in the toast notification", "• Bulk fix failures are logged individually with finding ID and error details" ] @@ -23428,9 +23428,9 @@ _OLD_V2_NOTES = r""" }, { "title": "Staging Folder Pre-Download Check", - "description": "Check your staging folder for existing files before downloading", + "description": "Check your import folder for existing files before downloading", "features": [ - "• Before searching Soulseek/YouTube, checks the staging folder for a matching file", + "• Before searching Soulseek/YouTube, checks the import folder for a matching file", "• Tag-based matching (Mutagen) with filename parsing fallback", "• On match, copies the file to transfer and runs normal post-processing", "• Staging scan cached per batch — only scans once for the entire download" @@ -24499,9 +24499,9 @@ def _resume_workers_after_scan(): def _run_soulsync_deep_scan(): """Deep scan for SoulSync standalone mode. - 1. Scans the Transfer folder for all audio files + 1. Scans the output folder for all audio files 2. Compares against soulsync DB records (by file_path) - 3. Untracked files → moved to Staging for auto-import processing + 3. Untracked files → moved to import folder for auto-import processing 4. Stale DB records (file gone) → removed from DB """ try: @@ -24510,7 +24510,7 @@ def _run_soulsync_deep_scan(): staging_path = docker_resolve_path(config_manager.get('import.staging_path', './Staging')) if not os.path.isdir(transfer_path): - _db_update_error_callback(f"Transfer folder not found: {transfer_path}") + _db_update_error_callback(f"Output folder not found: {transfer_path}") return print(f"[SoulSync Deep Scan] Starting — Transfer: {transfer_path}") @@ -26851,8 +26851,8 @@ def _run_duplicate_cleaner(): if not transfer_folder or not os.path.exists(transfer_folder): with duplicate_cleaner_lock: duplicate_cleaner_state["status"] = "error" - duplicate_cleaner_state["phase"] = "Transfer folder not configured or does not exist" - duplicate_cleaner_state["error_message"] = "Please configure Transfer folder in settings" + duplicate_cleaner_state["phase"] = "Output folder not configured or does not exist" + duplicate_cleaner_state["error_message"] = "Please configure output folder in settings" print(f"[Duplicate Cleaner] Transfer folder not found: {transfer_folder}") return diff --git a/webui/index.html b/webui/index.html index 39384333..5de14518 100644 --- a/webui/index.html +++ b/webui/index.html @@ -4422,7 +4422,7 @@
- + Files in this folder are your library. Configure the path in the Paths section.
@@ -4449,7 +4449,7 @@
- +
@@ -4457,7 +4457,7 @@
- +
@@ -4465,7 +4465,7 @@
- +
@@ -6060,13 +6060,13 @@

Import Music

-
- Staging folder: loading... + Import folder: loading...
@@ -6097,7 +6097,7 @@ Auto-Import Disabled - @@ -6136,8 +6136,8 @@
-

Enable auto-import to watch your staging folder for new music.

-

Drop album folders or single tracks into your staging directory and SoulSync will identify, match, and import them automatically.

+

Enable auto-import to watch your import folder for new music.

+

Drop album folders or single tracks into your import folder and SoulSync will identify, match, and import them automatically.

@@ -6147,7 +6147,7 @@
-
Suggested from your staging folder
+
Suggested from your import folder
@@ -6199,7 +6199,7 @@
-
Navigate to this page to scan your staging folder for audio files.
+
Navigate to this page to scan your import folder for audio files.
@@ -6520,7 +6520,7 @@
-

Detect and remove duplicate tracks in Transfer folder

+

Detect and remove duplicate tracks in output folder

Files Scanned: diff --git a/webui/static/docs.js b/webui/static/docs.js index 1c335e73..c7d8e0dc 100644 --- a/webui/static/docs.js +++ b/webui/static/docs.js @@ -63,7 +63,7 @@ const DOCS_SECTIONS = [
  • 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.
  • Media Server — Connect Plex, Jellyfin, or Navidrome so SoulSync knows where your library lives and can trigger scans.
  • Spotify (Recommended) — Connect Spotify for the richest metadata. Create an app at developer.spotify.com, enter your Client ID and Secret, then click Authenticate.
    • -
  • 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.
    • +
  • Input Path — Set your input and output paths in the Download Settings section. The output 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. Spotify and other services add metadata enrichment but aren't strictly required — iTunes/Apple Music and Deezer are always available as free fallbacks.
    @@ -105,7 +105,7 @@ const DOCS_SECTIONS = [
  • Artists — Search artists, manage your watchlist, scan for new releases
  • Automations — Create scheduled tasks and event-driven workflows
  • Library — Browse and manage your music collection with standard or enhanced views
    • -
  • Import — Import music files from a staging folder with album/track matching
    • +
  • Import — Import music files from an import folder with album/track matching
  • Settings — Configure services, download preferences, quality profiles, and more
    • ${docsImg('gs-interface.jpg', 'SoulSync interface layout')} @@ -126,9 +126,9 @@ const DOCS_SECTIONS = [ - - - + + +
    FolderDefault (Docker)Purpose
    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.
    Input Path/app/downloadsWhere slskd/YouTube/Tidal/Qobuz initially saves downloaded files. This is a temporary holding area — files should not stay here permanently.
    Output Path/app/TransferWhere post-processed files are moved after tagging and renaming. This must be the folder your media server (Plex/Jellyfin/Navidrome) monitors.
    Import Path/app/StagingFor the Import feature only. Drop audio files here to import them into your library via the Import page.
    ${docsImg('gs-folders.jpg', 'Download settings folder configuration')} @@ -137,13 +137,13 @@ const DOCS_SECTIONS = [
    ℹ️
    The complete download-to-library pipeline:

    1. You search for music in SoulSync and click download
    - 2. SoulSync tells slskd to download the file → slskd saves it to its download folder
    - 3. SoulSync detects the completed download in the Download Path
    + 2. SoulSync tells slskd to download the file → slskd saves it to its input folder
    + 3. SoulSync detects the completed download in the Input Path
    4. Post-processing runs: AcoustID verification → metadata tagging → cover art embedding → lyrics fetch
    5. File is renamed and organized (e.g., Artist/Album/01 - Title.flac)
    - 6. File is moved from Download Path → Transfer Path
    + 6. File is moved from Input Path → Output Path
    7. Media server scan is triggered → file appears in your library

    - If any step fails, the pipeline stops. The most common failure point is Step 3 — SoulSync can't find the file because the Download Path doesn't match where slskd actually saved it. + If any step fails, the pipeline stops. The most common failure point is Step 3 — SoulSync can't find the file because the Input Path doesn't match where slskd actually saved it.

    Docker Setup: The Full Picture

    @@ -163,31 +163,31 @@ const DOCS_SECTIONS = [ /app/downloads/ ← same files as /mnt/data/slskd-downloads/
    /app/Transfer/ ← same files as /mnt/media/music/

    SoulSync Settings (what you enter in the app)
    - Download Path: /app/downloads
    - Transfer Path: /app/Transfer + Input Path: /app/downloads
    + Output Path: /app/Transfer

    The #1 Mistake: Not Configuring App Settings

    Many users set up their docker-compose volumes correctly but never open SoulSync Settings to configure the paths. The app defaults may not match your volume mounts. You must go to Settings → Download Settings and verify that:

    ⚠️
    "I set up my docker-compose but nothing transfers" — this almost always means the app settings weren't configured. Docker-compose makes the folders accessible. The app settings tell SoulSync where to look. Both are required.
    -

    The #2 Mistake: Download Path Doesn't Match slskd

    -

    The Download Path in SoulSync must point to the exact same physical folder where slskd saves its completed downloads. If they don't match, SoulSync can't find the files and post-processing fails silently.

    +

    The #2 Mistake: Input Path Doesn't Match slskd

    +

    The Input Path in SoulSync must point to the exact same physical folder where slskd saves its completed downloads. If they don't match, SoulSync can't find the files and post-processing fails silently.

    ℹ️
    - Both SoulSync and slskd must see the same download folder.

    + Both SoulSync and slskd must see the same input folder.

    slskd container:
    • slskd downloads to /downloads/complete inside its own container
    • slskd docker-compose: - /mnt/data/slskd-downloads:/downloads/complete

    SoulSync container:
    • SoulSync docker-compose: - /mnt/data/slskd-downloads:/app/downloads (same host folder!)
    - • SoulSync Setting: Download Path = /app/downloads

    + • SoulSync Setting: Input Path = /app/downloads

    The key: both containers mount the same host folder (/mnt/data/slskd-downloads). The container-internal paths can be different — that's fine. What matters is they point to the same physical directory on your server.
    @@ -205,18 +205,18 @@ const DOCS_SECTIONS = [ -

    Transfer Path = Media Server's Music Folder

    -

    Your Transfer Path must ultimately point to the same physical directory your media server monitors. This is how new music appears in Plex/Jellyfin/Navidrome.

    +

    Output Path = Media Server's Music Folder

    +

    Your Output Path must ultimately point to the same physical directory your media server monitors. This is how new music appears in Plex/Jellyfin/Navidrome.

    💡
    Example with Plex:

    • Plex monitors /mnt/media/music on the host
    • SoulSync docker-compose: - /mnt/media/music:/app/Transfer:rw
    - • SoulSync Settings: Transfer Path = /app/Transfer

    + • SoulSync Settings: Output Path = /app/Transfer

    Result: SoulSync writes to /app/Transfer inside the container → appears at /mnt/media/music on the host → Plex sees it and adds it to your library.

    Complete Docker Compose Example (slskd + SoulSync)

    -

    Here's a working example showing both slskd and SoulSync configured to share the same download folder:

    +

    Here's a working example showing both slskd and SoulSync configured to share the same input folder:

    📋
    # docker-compose.yml
    services:
    @@ -239,17 +239,17 @@ const DOCS_SECTIONS = [       - /docker/soulsync/staging:/app/Staging
          - soulsync_database:/app/data

    # Then in SoulSync Settings:
    - # Download Path: /app/downloads
    - # Transfer Path: /app/Transfer + # Input Path: /app/downloads
    + # Output Path: /app/Transfer
    ${docsImg('gs-docker.jpg', 'Docker compose configuration')}

    Setup Checklist

    Go through every item. If you miss any single one, the pipeline will break:

      -
    1. slskd download folder is mounted in SoulSync's container — Both containers must mount the same host directory. The host paths (left side of :) must be identical.
      2. -
    2. Media server's music folder is mounted as Transfer — Mount the folder your Plex/Jellyfin/Navidrome monitors as /app/Transfer with :rw permissions.
      3. -
    3. SoulSync Settings are configured — Open Settings → Download Settings. Set Download Path to /app/downloads and Transfer Path to /app/Transfer (or whatever container paths you used on the right side of :).
      4. +
    4. slskd input folder is mounted in SoulSync's container — Both containers must mount the same host directory. The host paths (left side of :) must be identical.
      5. +
    5. Media server's music folder is mounted as Output — Mount the folder your Plex/Jellyfin/Navidrome monitors as /app/Transfer with :rw permissions.
      6. +
    6. SoulSync Settings are configured — Open Settings → Download Settings. Set Input Path to /app/downloads and Output Path to /app/Transfer (or whatever container paths you used on the right side of :).
    7. slskd URL and API key are set — In Settings → Soulseek, enter your slskd URL (e.g., http://slskd:5030 or http://host.docker.internal:5030) and API key.
    8. PUID/PGID match your host user — Run id on your host. Set those values in docker-compose environment variables. Both slskd and SoulSync should use the same PUID/PGID.
    9. Test with one track — Download a single track. Watch the logs. If it downloads but doesn't transfer, the paths are wrong.
      10. @@ -259,7 +259,7 @@ const DOCS_SECTIONS = [

      If paths are correct but files still won't transfer, it's usually a permissions issue. SoulSync needs read + write access to all three folders.

      @@ -270,7 +270,7 @@ const DOCS_SECTIONS = [
    10. Verify downloads are visible: docker exec soulsync-webui ls -la /app/downloads — you should see slskd's downloaded files here. If empty or "No such file or directory", your volume mount is wrong.
    11. Verify Transfer is writable: docker exec soulsync-webui touch /app/Transfer/test.txt && echo "OK" — then check that test.txt appears in your media server's music folder on the host. Clean up after: rm /mnt/media/music/test.txt
    12. Verify permissions: docker exec soulsync-webui id — the uid and gid should match your PUID/PGID values.
      13. -
    13. Verify app settings: Open SoulSync Settings → Download Settings. Confirm the Download Path and Transfer Path show container paths (like /app/downloads), not host paths.
      14. +
    14. Verify app settings: Open SoulSync Settings → Download Settings. Confirm the Input Path and Output Path show container paths (like /app/downloads), not host paths.
    15. Test a single download: Search for a track, download it, and watch the logs. Enable DEBUG logging in Settings for full detail. Check logs/app.log for any path errors.
    @@ -278,13 +278,13 @@ const DOCS_SECTIONS = [ - - - - - - - + + + + + + +
    SymptomLikely CauseFix
    Files download but never transferApp settings not configured — docker-compose volumes are set but SoulSync Settings still have defaults or wrong pathsOpen Settings → Download Settings and set Download Path + Transfer Path to your container-side mount paths.
    Post-processing log is emptySoulSync can't find the downloaded file at the expected path — the Download Path in Settings doesn't match where slskd actually saves files inside the containerRun docker exec soulsync-webui ls /app/downloads to see what's actually there. The Download Path in Settings must match this path exactly.
    Same tracks downloading multiple timesPost-processing fails so SoulSync thinks the track was never downloaded successfully. On resume, it tries again.Fix the folder paths first. Once post-processing works, files move to Transfer and SoulSync knows they exist.
    Files not renamed properlyPost-processing isn't running (path mismatch) or file organization is disabled in SettingsVerify File Organization is enabled in Settings → Processing & Organization. Fix Download Path first.
    Permission denied in logsContainer user can't write to the Transfer folder on the hostSet PUID/PGID to match the host user that owns the music folder. Run chmod -R 755 on the Transfer host folder.
    Media server doesn't see new filesTransfer Path doesn't map to the folder your media server monitorsEnsure the host path in your SoulSync volume mount (/mnt/media/music:/app/Transfer) is the same folder Plex/Jellyfin/Navidrome watches.
    slskd downloads work fine on their own but not through SoulSyncslskd's download folder and SoulSync's Download Path point to different physical locationsBoth containers must mount the same host directory. Check the left side of : in both docker-compose volume entries — they must match.
    Files download but never transferApp settings not configured — docker-compose volumes are set but SoulSync Settings still have defaults or wrong pathsOpen Settings → Download Settings and set Input Path + Output Path to your container-side mount paths.
    Post-processing log is emptySoulSync can't find the downloaded file at the expected path — the Input Path in Settings doesn't match where slskd actually saves files inside the containerRun docker exec soulsync-webui ls /app/downloads to see what's actually there. The Input Path in Settings must match this path exactly.
    Same tracks downloading multiple timesPost-processing fails so SoulSync thinks the track was never downloaded successfully. On resume, it tries again.Fix the folder paths first. Once post-processing works, files move to the output folder and SoulSync knows they exist.
    Files not renamed properlyPost-processing isn't running (path mismatch) or file organization is disabled in SettingsVerify File Organization is enabled in Settings → Processing & Organization. Fix Input Path first.
    Permission denied in logsContainer user can't write to the output folder on the hostSet PUID/PGID to match the host user that owns the music folder. Run chmod -R 755 on the output host folder.
    Media server doesn't see new filesOutput Path doesn't map to the folder your media server monitorsEnsure the host path in your SoulSync volume mount (/mnt/media/music:/app/Transfer) is the same folder Plex/Jellyfin/Navidrome watches.
    slskd downloads work fine on their own but not through SoulSyncslskd's download folder and SoulSync's Input Path point to different physical locationsBoth containers must mount the same host directory. Check the left side of : in both docker-compose volume entries — they must match.
    💡
    Still stuck? Enable DEBUG logging in Settings, download a single track, and check logs/app.log. The post-processing log will show exactly where the file pipeline breaks — whether it's a path not found, permission denied, or verification failure. If the post-processing log is empty, the issue is almost certainly a path mismatch (SoulSync never found the file to process).
    @@ -392,7 +392,7 @@ const DOCS_SECTIONS = [

    How to: Download an Album

    Goal: Find an album and download it to your library with full metadata, cover art, and proper file organization.

    -

    Prerequisites: At least one download source connected (Soulseek, YouTube, Tidal, or Qobuz). Download and Transfer paths configured.

    +

    Prerequisites: At least one download source connected (Soulseek, YouTube, Tidal, or Qobuz). Input and Output paths configured.

    1. Open Search — Click the Search page in the sidebar (make sure Enhanced Search is active)
    2. Type the album name — Results appear in a categorized dropdown: Artists, Albums, Singles & EPs, Tracks
      3. @@ -401,7 +401,7 @@ const DOCS_SECTIONS = [
    3. Click Download — SoulSync searches for each track, downloads, tags, and organizes the files automatically
    ${docsImg('wf-download-album.gif', 'Downloading an album')} -

    Result: Tracks appear in your Transfer folder as Artist/Album/01 - Title.flac and your media server is notified to scan.

    +

    Result: Tracks appear in your output folder as Artist/Album/01 - Title.flac and your media server is notified to scan.

    💡
    If a track fails to download, click the retry icon or use the candidate selector to pick an alternative source file from a different user.
    @@ -432,7 +432,7 @@ const DOCS_SECTIONS = [

    How to: Import Existing Music

    Goal: Bring music files you already have into SoulSync with proper metadata and organization.

      -
    1. Place files in your staging folder — Put album folders (e.g., Artist - Album/) in the Staging path configured in Settings
      2. +
    2. Place files in your import folder — Put album folders (e.g., Artist - Album/) in the Import Path configured in Settings
    3. Go to the Import page — SoulSync detects the files and suggests album matches
    4. Search for the correct album — If the auto-suggestion is wrong, search Spotify/iTunes for the right album
    5. Match tracks — Drag-and-drop files onto the correct track slots, or click Auto-Match
      6. @@ -450,7 +450,7 @@ const DOCS_SECTIONS = [
    6. Click Test Connection — Verify the connection is working. A green checkmark confirms success
    ${docsImg('wf-media-server.gif', 'Connecting media server')} -
    💡
    Make sure your Transfer Path points to the same folder your media server monitors. This is how new downloads automatically appear in your library.
    +
    💡
    Make sure your Output Path points to the same folder your media server monitors. This is how new downloads automatically appear in your library.
    ` }, @@ -576,7 +576,7 @@ const DOCS_SECTIONS = [ JobWhat It Does Track Number RepairFixes missing or incorrect track numbers by comparing against official tracklists - Orphan File DetectorFinds audio files in your transfer folder not tracked in the database. Can move to staging or delete. + Orphan File DetectorFinds audio files in your output folder not tracked in the database. Can move to import folder or delete. Dead File CleanerRemoves database entries pointing to files that no longer exist on disk Duplicate DetectorIdentifies duplicate tracks by fingerprint or metadata match AcoustID ScannerBatch audio fingerprint verification across your library @@ -834,7 +834,7 @@ const DOCS_SECTIONS = [
  • 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).
  • 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).
  • Cover Art Embedding — Album artwork is downloaded from the metadata source and embedded directly into the audio file.
    • -
  • 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 for zero-padded "01" or $discnum for unpadded "1" in your template for manual control).
    • +
  • File Organization — The file is renamed and moved to your output 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 for zero-padded "01" or $discnum for unpadded "1" in your template for manual control).
  • 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.
  • Lossy Copy — If enabled in settings, a lower-bitrate copy is created alongside the original (useful for mobile device syncing).
  • Media Server Scan — Your media server (Plex/Jellyfin) is notified to scan for the new file. Navidrome auto-detects changes.
    • @@ -1111,8 +1111,8 @@ const DOCS_SECTIONS = [ Backup DatabaseCreate a timestamped database backup Refresh Beatport CacheScrape Beatport homepage and warm the data cache Clean Search HistoryRemove old searches from Soulseek (keeps 50 most recent) - Clean Completed DownloadsClear completed downloads and empty directories from the download folder - Full CleanupClear quarantine, download queue, staging folder, and search history in one sweep + Clean Completed DownloadsClear completed downloads and empty directories from the input folder + Full CleanupClear quarantine, download queue, import folder, and search history in one sweep Notify OnlyNo action — just trigger notifications @@ -1250,7 +1250,7 @@ const DOCS_SECTIONS = [

    Library Issues

    The Issues page tracks problems detected in your library by the repair worker. Issues are categorized by type and severity:

    -

    After matching, the import process tags files with the official metadata (title, artist, album, track number, cover art) and moves them to your transfer path following the standard file organization template.

    +

    After matching, the import process tags files with the official metadata (title, artist, album, track number, cover art) and moves them to your output path following the standard file organization template.

    Import from Text File

    @@ -1422,9 +1422,9 @@ const DOCS_SECTIONS = [

    Download Settings